<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
<title>Generic TriBITS Project, Build, Test, and Install Quick Reference Guide</title>
<meta name="author" content="Roscoe A. Bartlett" />
<meta name="date" content="2015-02-25" />
<style type="text/css">

/*
:Author: David Goodger (goodger@python.org)
:Id: $Id: html4css1.css 7614 2013-02-21 15:55:51Z milde $
:Copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.

See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/

/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
  border: 0 }

table.borderless td, table.borderless th {
  /* Override padding for "table.docutils td" with "! important".
     The right padding separates the table cells. */
  padding: 0 0.5em 0 0 ! important }

.first {
  /* Override more specific margin styles with "! important". */
  margin-top: 0 ! important }

.last, .with-subtitle {
  margin-bottom: 0 ! important }

.hidden {
  display: none }

a.toc-backref {
  text-decoration: none ;
  color: black }

blockquote.epigraph {
  margin: 2em 5em ; }

dl.docutils dd {
  margin-bottom: 0.5em }

object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
  overflow: hidden;
}

/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
  font-weight: bold }
*/

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title, .code .error {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

/* Uncomment (and remove this text!) to get reduced vertical space in
   compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
  margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle {
  margin-top: 0.5em }
*/

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em ;
  margin-right: 2em }

div.footer, div.header {
  clear: both;
  font-size: smaller }

div.line-block {
  display: block ;
  margin-top: 1em ;
  margin-bottom: 1em }

div.line-block div.line-block {
  margin-top: 0 ;
  margin-bottom: 0 ;
  margin-left: 1.5em }

div.sidebar {
  margin: 0 0 0.5em 1em ;
  border: medium outset ;
  padding: 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
  margin-top: 0.4em }

h1.title {
  text-align: center }

h2.subtitle {
  text-align: center }

hr.docutils {
  width: 75% }

img.align-left, .figure.align-left, object.align-left {
  clear: left ;
  float: left ;
  margin-right: 1em }

img.align-right, .figure.align-right, object.align-right {
  clear: right ;
  float: right ;
  margin-left: 1em }

img.align-center, .figure.align-center, object.align-center {
  display: block;
  margin-left: auto;
  margin-right: auto;
}

.align-left {
  text-align: left }

.align-center {
  clear: both ;
  text-align: center }

.align-right {
  text-align: right }

/* reset inner alignment in figures */
div.align-right {
  text-align: inherit }

/* div.align-center * { */
/*   text-align: left } */

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font: inherit }

pre.literal-block, pre.doctest-block, pre.math, pre.code {
  margin-left: 2em ;
  margin-right: 2em }

pre.code .ln { color: grey; } /* line numbers */
pre.code, code { background-color: #eeeeee }
pre.code .comment, code .comment { color: #5C6576 }
pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold }
pre.code .literal.string, code .literal.string { color: #0C5404 }
pre.code .name.builtin, code .name.builtin { color: #352B84 }
pre.code .deleted, code .deleted { background-color: #DEB0A1}
pre.code .inserted, code .inserted { background-color: #A3D289}

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

span.section-subtitle {
  /* font-size relative to parent (h1..h6 element) */
  font-size: 80% }

table.citation {
  border-left: solid 1px gray;
  margin-left: 1px }

table.docinfo {
  margin: 2em 4em }

table.docutils {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.footnote {
  border-left: solid 1px black;
  margin-left: 1px }

table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

table.docutils th.field-name, table.docinfo th.docinfo-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap ;
  padding-left: 0 }

/* "booktabs" style (no vertical lines) */
table.docutils.booktabs {
  border: 0px;
  border-top: 2px solid;
  border-bottom: 2px solid;
  border-collapse: collapse;
}
table.docutils.booktabs * {
  border: 0px;
}
table.docutils.booktabs th {
  border-bottom: thin solid;
  text-align: left;
}

h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
  font-size: 100% }

ul.auto-toc {
  list-style-type: none }

</style>
</head>
<body>
<div class="document" id="generic-tribits-project-build-test-and-install-quick-reference-guide">
<h1 class="title">Generic TriBITS Project, Build, Test, and Install Quick Reference Guide</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Roscoe A. Bartlett</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first last reference external" href="mailto:bartlett.roscoe&#64;gmail.com">bartlett.roscoe&#64;gmail.com</a></td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2015-02-25</td></tr>
<tr class="field"><th class="docinfo-name">Version:</th><td class="field-body"><div class="first last system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">TribitsBuildQuickRef.rst</tt>, line 8)</p>
Cannot extract empty bibliographic field &quot;Version&quot;.</div>
</td>
</tr>
</tbody>
</table>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Abstract:</th><td class="field-body">This document is generated from the generic template body document <tt class="docutils literal">TribitsBuildQickRefBody.rst</tt> and provides a general project-independent quick reference on how to configure, build, test, and install a project that uses the TriBITS CMake build system.  The primary audience of this particular build of this document are TriBITS project developers themselves.  A project-specific version of this document should be created and accessed by users of a particular TriBITS-based project.</td>
</tr>
</tbody>
</table>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="auto-toc simple">
<li><a class="reference internal" href="#introduction" id="id1">1&nbsp;&nbsp;&nbsp;Introduction</a></li>
<li><a class="reference internal" href="#getting-set-up-to-use-cmake" id="id2">2&nbsp;&nbsp;&nbsp;Getting set up to use CMake</a><ul class="auto-toc">
<li><a class="reference internal" href="#installing-a-binary-release-of-cmake-casual-users" id="id3">2.1&nbsp;&nbsp;&nbsp;Installing a binary release of CMake [casual users]</a></li>
<li><a class="reference internal" href="#installing-cmake-from-source-developers-and-experienced-users" id="id4">2.2&nbsp;&nbsp;&nbsp;Installing CMake from source [developers and experienced users]</a></li>
</ul>
</li>
<li><a class="reference internal" href="#getting-cmake-help" id="id5">3&nbsp;&nbsp;&nbsp;Getting CMake Help</a><ul class="auto-toc">
<li><a class="reference internal" href="#finding-cmake-help-at-the-website" id="id6">3.1&nbsp;&nbsp;&nbsp;Finding CMake help at the website</a></li>
<li><a class="reference internal" href="#building-cmake-help-locally" id="id7">3.2&nbsp;&nbsp;&nbsp;Building CMake help locally</a></li>
</ul>
</li>
<li><a class="reference internal" href="#configuring-makefile-generator" id="id8">4&nbsp;&nbsp;&nbsp;Configuring (Makefile Generator)</a><ul class="auto-toc">
<li><a class="reference internal" href="#setting-up-a-build-directory" id="id9">4.1&nbsp;&nbsp;&nbsp;Setting up a build directory</a></li>
<li><a class="reference internal" href="#basic-configuration" id="id10">4.2&nbsp;&nbsp;&nbsp;Basic configuration</a></li>
<li><a class="reference internal" href="#selecting-the-list-of-packages-to-enable" id="id11">4.3&nbsp;&nbsp;&nbsp;Selecting the list of packages to enable</a><ul class="auto-toc">
<li><a class="reference internal" href="#determine-the-list-of-packages-that-can-be-enabled" id="id12">4.3.1&nbsp;&nbsp;&nbsp;Determine the list of packages that can be enabled</a></li>
<li><a class="reference internal" href="#print-package-dependencies" id="id13">4.3.2&nbsp;&nbsp;&nbsp;Print package dependencies</a></li>
<li><a class="reference internal" href="#enable-a-set-of-packages" id="id14">4.3.3&nbsp;&nbsp;&nbsp;Enable a set of packages</a></li>
<li><a class="reference internal" href="#enable-to-test-all-effects-of-changing-a-given-package-s" id="id15">4.3.4&nbsp;&nbsp;&nbsp;Enable to test all effects of changing a given package(s)</a></li>
<li><a class="reference internal" href="#enable-all-packages-with-tests-and-examples" id="id16">4.3.5&nbsp;&nbsp;&nbsp;Enable all packages with tests and examples</a></li>
<li><a class="reference internal" href="#disable-a-package-and-all-its-dependencies" id="id17">4.3.6&nbsp;&nbsp;&nbsp;Disable a package and all its dependencies</a></li>
<li><a class="reference internal" href="#remove-all-package-enables-in-the-cache" id="id18">4.3.7&nbsp;&nbsp;&nbsp;Remove all package enables in the cache</a></li>
</ul>
</li>
<li><a class="reference internal" href="#selecting-compiler-and-linker-options" id="id19">4.4&nbsp;&nbsp;&nbsp;Selecting compiler and linker options</a></li>
<li><a class="reference internal" href="#enabling-support-for-c-11" id="id20">4.5&nbsp;&nbsp;&nbsp;Enabling support for C++11</a></li>
<li><a class="reference internal" href="#enabling-explicit-template-instantiation-for-c" id="id21">4.6&nbsp;&nbsp;&nbsp;Enabling explicit template instantiation for C++</a></li>
<li><a class="reference internal" href="#disabling-the-fortran-compiler-and-all-fortran-code" id="id22">4.7&nbsp;&nbsp;&nbsp;Disabling the Fortran compiler and all Fortran code</a></li>
<li><a class="reference internal" href="#enabling-runtime-debug-checking" id="id23">4.8&nbsp;&nbsp;&nbsp;Enabling runtime debug checking</a></li>
<li><a class="reference internal" href="#configuring-with-mpi-support" id="id24">4.9&nbsp;&nbsp;&nbsp;Configuring with MPI support</a></li>
<li><a class="reference internal" href="#configuring-for-openmp-support" id="id25">4.10&nbsp;&nbsp;&nbsp;Configuring for OpenMP support</a></li>
<li><a class="reference internal" href="#building-shared-libraries" id="id26">4.11&nbsp;&nbsp;&nbsp;Building shared libraries</a></li>
<li><a class="reference internal" href="#building-static-libraries-and-executables" id="id27">4.12&nbsp;&nbsp;&nbsp;Building static libraries and executables</a></li>
<li><a class="reference internal" href="#enabling-support-for-an-optional-third-party-library-tpl" id="id28">4.13&nbsp;&nbsp;&nbsp;Enabling support for an optional Third-Party Library (TPL)</a></li>
<li><a class="reference internal" href="#disabling-support-for-a-third-party-library-tpl" id="id29">4.14&nbsp;&nbsp;&nbsp;Disabling support for a Third-Party Library (TPL)</a></li>
<li><a class="reference internal" href="#disabling-tentatively-enabled-tpls" id="id30">4.15&nbsp;&nbsp;&nbsp;Disabling tentatively enabled TPLs</a></li>
<li><a class="reference internal" href="#generating-verbose-output" id="id31">4.16&nbsp;&nbsp;&nbsp;Generating verbose output</a></li>
<li><a class="reference internal" href="#enabling-disabling-deprecated-warnings" id="id32">4.17&nbsp;&nbsp;&nbsp;Enabling/disabling deprecated warnings</a></li>
<li><a class="reference internal" href="#disabling-deprecated-code" id="id33">4.18&nbsp;&nbsp;&nbsp;Disabling deprecated code</a></li>
<li><a class="reference internal" href="#outputting-package-dependency-information" id="id34">4.19&nbsp;&nbsp;&nbsp;Outputting package dependency information</a></li>
<li><a class="reference internal" href="#enabling-different-test-categories" id="id35">4.20&nbsp;&nbsp;&nbsp;Enabling different test categories</a></li>
<li><a class="reference internal" href="#disabling-specific-tests" id="id36">4.21&nbsp;&nbsp;&nbsp;Disabling specific tests</a></li>
<li><a class="reference internal" href="#trace-test-addition-or-exclusion" id="id37">4.22&nbsp;&nbsp;&nbsp;Trace test addition or exclusion</a></li>
<li><a class="reference internal" href="#setting-test-timeouts-at-configure-time" id="id38">4.23&nbsp;&nbsp;&nbsp;Setting test timeouts at configure time</a></li>
<li><a class="reference internal" href="#scaling-test-timeouts-at-configure-time" id="id39">4.24&nbsp;&nbsp;&nbsp;Scaling test timeouts at configure time</a></li>
<li><a class="reference internal" href="#enabling-support-for-coverage-testing" id="id40">4.25&nbsp;&nbsp;&nbsp;Enabling support for coverage testing</a></li>
<li><a class="reference internal" href="#viewing-configure-options-and-documentation" id="id41">4.26&nbsp;&nbsp;&nbsp;Viewing configure options and documentation</a></li>
<li><a class="reference internal" href="#enabling-extra-repositories-with-add-on-packages" id="id42">4.27&nbsp;&nbsp;&nbsp;Enabling extra repositories with add-on packages:</a></li>
<li><a class="reference internal" href="#enabling-extra-repositories-through-a-file" id="id43">4.28&nbsp;&nbsp;&nbsp;Enabling extra repositories through a file</a></li>
<li><a class="reference internal" href="#reconfiguring-completely-from-scratch" id="id44">4.29&nbsp;&nbsp;&nbsp;Reconfiguring completely from scratch</a></li>
<li><a class="reference internal" href="#viewing-configure-errors" id="id45">4.30&nbsp;&nbsp;&nbsp;Viewing configure errors</a></li>
<li><a class="reference internal" href="#adding-configure-timers" id="id46">4.31&nbsp;&nbsp;&nbsp;Adding configure timers</a></li>
<li><a class="reference internal" href="#generating-export-files" id="id47">4.32&nbsp;&nbsp;&nbsp;Generating export files</a></li>
<li><a class="reference internal" href="#generating-a-project-repo-version-file" id="id48">4.33&nbsp;&nbsp;&nbsp;Generating a project repo version file</a></li>
<li><a class="reference internal" href="#cmake-configure-time-development-mode-and-debug-checking" id="id49">4.34&nbsp;&nbsp;&nbsp;CMake configure-time development mode and debug checking</a></li>
</ul>
</li>
<li><a class="reference internal" href="#building-makefile-generator" id="id50">5&nbsp;&nbsp;&nbsp;Building (Makefile generator)</a><ul class="auto-toc">
<li><a class="reference internal" href="#building-all-targets" id="id51">5.1&nbsp;&nbsp;&nbsp;Building all targets</a></li>
<li><a class="reference internal" href="#discovering-what-targets-are-available-to-build" id="id52">5.2&nbsp;&nbsp;&nbsp;Discovering what targets are available to build</a></li>
<li><a class="reference internal" href="#building-all-of-the-targets-for-a-package" id="id53">5.3&nbsp;&nbsp;&nbsp;Building all of the targets for a package</a></li>
<li><a class="reference internal" href="#building-all-of-the-libraries-for-a-package" id="id54">5.4&nbsp;&nbsp;&nbsp;Building all of the libraries for a package</a></li>
<li><a class="reference internal" href="#building-all-of-the-libraries-for-all-enabled-packages" id="id55">5.5&nbsp;&nbsp;&nbsp;Building all of the libraries for all enabled packages</a></li>
<li><a class="reference internal" href="#building-a-single-object-file" id="id56">5.6&nbsp;&nbsp;&nbsp;Building a single object file</a></li>
<li><a class="reference internal" href="#building-with-verbose-output-without-reconfiguring" id="id57">5.7&nbsp;&nbsp;&nbsp;Building with verbose output without reconfiguring</a></li>
<li><a class="reference internal" href="#relink-a-target-without-considering-dependencies" id="id58">5.8&nbsp;&nbsp;&nbsp;Relink a target without considering dependencies</a></li>
</ul>
</li>
<li><a class="reference internal" href="#testing-with-ctest" id="id59">6&nbsp;&nbsp;&nbsp;Testing with CTest</a><ul class="auto-toc">
<li><a class="reference internal" href="#running-all-tests" id="id60">6.1&nbsp;&nbsp;&nbsp;Running all tests</a></li>
<li><a class="reference internal" href="#only-running-tests-for-a-single-package" id="id61">6.2&nbsp;&nbsp;&nbsp;Only running tests for a single package</a></li>
<li><a class="reference internal" href="#running-a-single-test-with-full-output-to-the-console" id="id62">6.3&nbsp;&nbsp;&nbsp;Running a single test with full output to the console</a></li>
<li><a class="reference internal" href="#overridding-test-timeouts" id="id63">6.4&nbsp;&nbsp;&nbsp;Overridding test timeouts</a></li>
<li><a class="reference internal" href="#running-memory-checking" id="id64">6.5&nbsp;&nbsp;&nbsp;Running memory checking</a></li>
</ul>
</li>
<li><a class="reference internal" href="#installing" id="id65">7&nbsp;&nbsp;&nbsp;Installing</a><ul class="auto-toc">
<li><a class="reference internal" href="#setting-the-install-prefix-at-configure-time" id="id66">7.1&nbsp;&nbsp;&nbsp;Setting the install prefix at configure time</a></li>
<li><a class="reference internal" href="#avoiding-installing-libraries-and-headers" id="id67">7.2&nbsp;&nbsp;&nbsp;Avoiding installing libraries and headers</a></li>
<li><a class="reference internal" href="#installing-the-software" id="id68">7.3&nbsp;&nbsp;&nbsp;Installing the software</a></li>
</ul>
</li>
<li><a class="reference internal" href="#packaging" id="id69">8&nbsp;&nbsp;&nbsp;Packaging</a><ul class="auto-toc">
<li><a class="reference internal" href="#creating-a-tarball-of-the-source-tree" id="id70">8.1&nbsp;&nbsp;&nbsp;Creating a tarball of the source tree</a></li>
</ul>
</li>
<li><a class="reference internal" href="#dashboard-submissions" id="id71">9&nbsp;&nbsp;&nbsp;Dashboard submissions</a></li>
</ul>
</div>
<div class="section" id="introduction">
<h1><a class="toc-backref" href="#id1">1&nbsp;&nbsp;&nbsp;Introduction</a></h1>
<p>This document is created using the script <tt class="docutils literal"><span class="pre">create-build-quickref.sh</span></tt> in this
directory which just runs:</p>
<pre class="literal-block">
$ ./create-project-build-quickref.py \
  --project-name=&quot;&lt;Project&gt;&quot; \
  --project-template-file=TribitsBuildQuickRefTemplate.rst \
  --file-base=TribitsBuildQuickRef
</pre>
<p>to generate this document.  In a project-specific version, <tt class="docutils literal">&lt;Project&gt;</tt> is
replaced with the actual project name (e.g. <tt class="docutils literal">Trilinos</tt>, or <tt class="docutils literal">TriBITS</tt>,
etc.).  This version of the generated document is referred to by the general
TribitsDeveloperGuide.[rst,html,pdf] document.</p>
<p>Below are given genetic versions of the sections that show up in every
project-specific build of this document.</p>
<!-- Common references to other documents -->
</div>
<div class="section" id="getting-set-up-to-use-cmake">
<h1><a class="toc-backref" href="#id2">2&nbsp;&nbsp;&nbsp;Getting set up to use CMake</a></h1>
<p>Before one can configure &lt;Project&gt; to be built, one must first obtain a
version of CMake on the system newer than 2.8.11 This guide assumes
that once CMake is installed that it will be in the default path with the name
<tt class="docutils literal">cmake</tt>.</p>
<div class="section" id="installing-a-binary-release-of-cmake-casual-users">
<h2><a class="toc-backref" href="#id3">2.1&nbsp;&nbsp;&nbsp;Installing a binary release of CMake [casual users]</a></h2>
<p>Download and install the binary (version 2.8.11 or greater is
recommended) from:</p>
<blockquote>
<a class="reference external" href="http://www.cmake.org/cmake/resources/software.html">http://www.cmake.org/cmake/resources/software.html</a></blockquote>
</div>
<div class="section" id="installing-cmake-from-source-developers-and-experienced-users">
<h2><a class="toc-backref" href="#id4">2.2&nbsp;&nbsp;&nbsp;Installing CMake from source [developers and experienced users]</a></h2>
<p>If you have access to the &lt;Project&gt; git repositories, then install CMake with:</p>
<pre class="literal-block">
$ $TRIBITS_BASE_DIR/python/install-cmake.py \
   --install-dir=&lt;INSTALL_BASE_DIR&gt; \
   --do-all
</pre>
<p>This will result in cmake and related CMake tools being installed in
&lt;INSTALL_BASE_DIR&gt;/bin.</p>
<p>Getting help for installing CMake with this script:</p>
<pre class="literal-block">
$ $TRIBITS_BASE_DIR/python/install-cmake.py --help
</pre>
<p>NOTE: you will want to read the help message about how to use sudo to
install in a privileged location (like the default /usr/local/bin).</p>
</div>
</div>
<div class="section" id="getting-cmake-help">
<h1><a class="toc-backref" href="#id5">3&nbsp;&nbsp;&nbsp;Getting CMake Help</a></h1>
<div class="section" id="finding-cmake-help-at-the-website">
<h2><a class="toc-backref" href="#id6">3.1&nbsp;&nbsp;&nbsp;Finding CMake help at the website</a></h2>
<blockquote>
<a class="reference external" href="http://www.cmake.org">http://www.cmake.org</a></blockquote>
</div>
<div class="section" id="building-cmake-help-locally">
<h2><a class="toc-backref" href="#id7">3.2&nbsp;&nbsp;&nbsp;Building CMake help locally</a></h2>
<p>To get help on CMake input options, run:</p>
<pre class="literal-block">
$ cmake --help
</pre>
<p>To get help on a single CMake function, run:</p>
<pre class="literal-block">
$ cmake --help-command &lt;command&gt;
</pre>
<p>To generate the entire documentation at once, run:</p>
<pre class="literal-block">
$ cmake --help-full cmake.help.html
</pre>
<p>(Open your web browser to the file cmake.help.html)</p>
</div>
</div>
<div class="section" id="configuring-makefile-generator">
<h1><a class="toc-backref" href="#id8">4&nbsp;&nbsp;&nbsp;Configuring (Makefile Generator)</a></h1>
<p>While CMake supports a number of different build generators (e.g. Eclipes,
XCode, MS Visual Studio, etc.) the primary generator most people use on
Unix/Linix system is make and CMake generates exceptional Makefiles.  The
materila in this section, while not exclusing to the makefile generator this
should be assumed as the default.</p>
<div class="section" id="setting-up-a-build-directory">
<h2><a class="toc-backref" href="#id9">4.1&nbsp;&nbsp;&nbsp;Setting up a build directory</a></h2>
<p>In order to configure, one must set up a build directory.  &lt;Project&gt; does
<em>not</em> support in-source builds so the build tree must be seprate from the
source tree.  The build tree can be created under the source tree such as
with:</p>
<pre class="literal-block">
$ $SOURCE_DIR
$ mkdir &lt;SOME_BUILD_DIR&gt;
$ cd &lt;SOME_BUILD_DIR&gt;
</pre>
<p>but it is generally recommended to create a build directory parallel from the
soruce tree.</p>
<p>NOTE: If you mistakenly try to configure for an in-source build (e.g. with
'cmake .') you will get an error message and instructions on how to resolve
the problem by deleting the generated CMakeCache.txt file (and other generated
files) and then follow directions on how to create a different build directory
as shown above.</p>
</div>
<div class="section" id="basic-configuration">
<h2><a class="toc-backref" href="#id10">4.2&nbsp;&nbsp;&nbsp;Basic configuration</a></h2>
<ol class="loweralpha">
<li><p class="first">Create a 'do-configure' script such as [Recommended]:</p>
<pre class="literal-block">
EXTRA_ARGS=$&#64;

cmake \
  -D CMAKE_BUILD_TYPE=DEBUG \
  -D &lt;Project&gt;_ENABLE_TESTS=ON \
  $EXTRA_ARGS \
  ${SOURCE_BASE}
</pre>
</li>
</ol>
<blockquote>
<p>and then run it with:</p>
<pre class="literal-block">
./do-configure [OTHER OPTIONS] -D&lt;Project&gt;_ENABLE_&lt;TRIBITS_PACKAGE&gt;=ON
</pre>
<p>where <tt class="docutils literal">&lt;TRIBITS_PACKAGE&gt;</tt> is a valid SE Package name (see above), etc. and
<tt class="docutils literal">SOURCE_BASE</tt> is set to the &lt;Project&gt; source base directory (or your can
just give it explicitly in the script).</p>
<p>See <cite>&lt;Project&gt;/sampleScripts/*cmake</cite> for examples of real <cite>do-configure</cite>
scripts for different platforms..</p>
<p>NOTE: If one has already configured once and one needs to configure from
scratch (needs to wipe clean defaults for cache variables, updates
compilers, other types of changes) then one will want to delete the local
CASL and other CMake-generated files before configuring again (see
<a class="reference internal" href="#reconfiguring-completely-from-scratch">Reconfiguring completely from scratch</a>).</p>
</blockquote>
<ol class="loweralpha simple" id="project-configure-options-file" start="2">
<li>Create a CMake file fragment and point to it [Recommended].</li>
</ol>
<blockquote>
<p>Create a do-configure script like:</p>
<pre class="literal-block">
EXTRA_ARGS=$&#64;

cmake \
  -D &lt;Project&gt;_CONFIGURE_OPTIONS_FILE:FILEPATH=MyConfigureOptions.cmake \
  -D &lt;Project&gt;_ENABLE_TESTS=ON \
  $EXTRA_ARGS \
  ${SOURCE_BASE}
</pre>
<p>where MyConfigureOptions.cmake might look like:</p>
<pre class="literal-block">
SET(CMAKE_BUILD_TYPE DEBUG CACHE STRING &quot;&quot;)
SET(&lt;Project&gt;_ENABLE_CHECKED_STL ON CACHE BOOL &quot;&quot;)
SET(BUILD_SHARED_LIBS ON CACHE BOOL &quot;&quot;)
...
</pre>
<p>Using a configuration fragment file allows for better reuse of configure
options across different configure scripts and better version control of
configure options.  Also, when this file changes, CMake will automatically
trigger a reconfgure during a make (because it knows about the file and will
check its time stamp).</p>
<p>NOTE: You can actually pass in a list of configuration fragment files
which will be read in the order they are given.</p>
<p>NOTE: You can use the <tt class="docutils literal">FORCE</tt> option in the <tt class="docutils literal">SET()</tt> shown above and that
will override any value of the options that might already be set.  However,
that will not allow the user to override the options on the CMake
comamndline using <tt class="docutils literal"><span class="pre">-D&lt;VAR&gt;=&lt;value&gt;</span></tt> so it is generally desired to use
<tt class="docutils literal">FORCE</tt>.</p>
</blockquote>
<ol class="loweralpha simple" start="3">
<li>Using ccmake to configure</li>
</ol>
<blockquote>
<pre class="literal-block">
$ ccmake $SOURCE_BASE
</pre>
</blockquote>
<ol class="loweralpha simple" start="4">
<li>Using the QT CMake configuration GUI:</li>
</ol>
<blockquote>
On systems where the QT CMake GUI is installed (e.g. Windows) the CMake GUI
can be a nice way to configure &lt;Project&gt; if you are a user.  To make your
configuration easily repeatable, you might want to create a fragment file
and just load it by setting <a class="reference internal" href="#project-configure-options-file">&lt;Project&gt;_CONFIGURE_OPTIONS_FILE</a> (see above)
in the GUI.</blockquote>
</div>
<div class="section" id="selecting-the-list-of-packages-to-enable">
<h2><a class="toc-backref" href="#id11">4.3&nbsp;&nbsp;&nbsp;Selecting the list of packages to enable</a></h2>
<p>The &lt;Project&gt; project is broken up into a set of packages that can be enabled
(or disbled).  For details and generic examples, see <a class="reference external" href="../developers_guide/TribitsDevelopersGuide.html#package-dependencies-and-enable-disable-logic">Package Dependencies and
Enable/Disable Logic</a> and <a class="reference external" href="../developers_guide/TribitsDevelopersGuide.html#tribits-dependency-handling-behaviors">TriBITS Dependency Handling Behaviors</a>.</p>
<p>See the following use cases:</p>
<ul class="simple">
<li><a class="reference internal" href="#determine-the-list-of-packages-that-can-be-enabled">Determine the list of packages that can be enabled</a></li>
<li><a class="reference internal" href="#print-package-dependencies">Print package dependencies</a></li>
<li><a class="reference internal" href="#enable-a-set-of-packages">Enable a set of packages</a></li>
<li><a class="reference internal" href="#enable-to-test-all-effects-of-changing-a-given-package-s">Enable to test all effects of changing a given package(s)</a></li>
<li><a class="reference internal" href="#enable-all-packages-with-tests-and-examples">Enable all packages with tests and examples</a></li>
<li><a class="reference internal" href="#disable-a-package-and-all-its-dependencies">Disable a package and all its dependencies</a></li>
<li><a class="reference internal" href="#remove-all-package-enables-in-the-cache">Remove all package enables in the cache</a></li>
</ul>
<div class="section" id="determine-the-list-of-packages-that-can-be-enabled">
<h3><a class="toc-backref" href="#id12">4.3.1&nbsp;&nbsp;&nbsp;Determine the list of packages that can be enabled</a></h3>
<p>In order to see the list of available &lt;Project&gt; SE Packages to enable, just
run a basic CMake configure, enabling nothing, and then grep the output to see
what packages are available to enable.  The full set of defined packages is
contained the lines starting with <tt class="docutils literal">'Final set of enabled SE packages'</tt> and
<tt class="docutils literal">'Final set of <span class="pre">non-enabled</span> SE packages'</tt>.  If no SE packages are enabled by
default (which is base behavior), the full list of packages will be listed on
the line <tt class="docutils literal">'Final set of <span class="pre">non-enabled</span> SE packages'</tt>.  Therefore, to see the
full list of defined packages, run:</p>
<pre class="literal-block">
./do-configure 2&gt;&amp;1 | grep &quot;Final set of .*enabled SE packages&quot;
</pre>
<p>Any of the packages shown on those lines can potentially be enabled using <tt class="docutils literal"><span class="pre">-D</span>
<span class="pre">&lt;Project&gt;_ENABLE_&lt;TRIBITS_PACKAGE&gt;=ON</span></tt> (unless they are set to disabled
for some reason, see the CMake output for package disable warnings).</p>
<p>Another way to see the full list of SE packages that can be enabled is to
configure with <a class="reference internal" href="#project-dump-package-dependencies">&lt;Project&gt;_DUMP_PACKAGE_DEPENDENCIES</a> = <tt class="docutils literal">ON</tt> and then grep
for <tt class="docutils literal">&lt;Project&gt;_SE_PACKAGES</tt> using, for example:</p>
<pre class="literal-block">
./do-configure 2&gt;&amp;1 | grep &quot;&lt;Project&gt;_SE_PACKAGES: &quot;
</pre>
</div>
<div class="section" id="print-package-dependencies">
<span id="project-dump-package-dependencies"></span><h3><a class="toc-backref" href="#id13">4.3.2&nbsp;&nbsp;&nbsp;Print package dependencies</a></h3>
<p>The set of package dependencies in a project will be printed in the <tt class="docutils literal">cmake</tt>
STDOUT by setting:</p>
<pre class="literal-block">
-D &lt;Project&gt;_DUMP_PACKAGE_DEPENDENCIES=ON
</pre>
<p>This will print the basic backward dependencies for each SE package.  To also
see the direct forward dependencies for each SE package, also include:</p>
<pre class="literal-block">
-D &lt;Project&gt;_DUMP_FORWARD_PACKAGE_DEPENDENCIES=ON
</pre>
<p>Both of these variables are automatically enabled when
<a class="reference internal" href="#project-verbose-configure">&lt;Project&gt;_VERBOSE_CONFIGURE</a> = <tt class="docutils literal">ON</tt>.</p>
</div>
<div class="section" id="enable-a-set-of-packages">
<h3><a class="toc-backref" href="#id14">4.3.3&nbsp;&nbsp;&nbsp;Enable a set of packages</a></h3>
<p>To enable an SE package <tt class="docutils literal">&lt;TRIBITS_PACKAGE&gt;</tt> (and optionally also its tests
and examples), configure with:</p>
<pre class="literal-block">
-D &lt;Project&gt;_ENABLE_&lt;TRIBITS_PACKAGE&gt;=ON \
-D &lt;Project&gt;_ENABLE_ALL_OPTIONAL_PACKAGES=ON \
-D &lt;Project&gt;_ENABLE_TESTS=ON \
</pre>
<p>This set of arguments allows a user to turn on <tt class="docutils literal">&lt;TRIBITS_PACKAGE&gt;</tt> as well
as all packages that <tt class="docutils literal">&lt;TRIBITS_PACKAGE&gt;</tt> can use.  All of the package's
optional &quot;can use&quot; upstream dependent packages are enabled with
<tt class="docutils literal"><span class="pre">-D&lt;Project&gt;_ENABLE_ALL_OPTIONAL_PACKAGES=ON</span></tt>.  However,
<tt class="docutils literal"><span class="pre">-D&lt;Project&gt;_ENABLE_TESTS=ON</span></tt> will only enable tests and examples for
<tt class="docutils literal">&lt;TRIBITS_PACKAGE&gt;</tt> (or any other packages specifically enabled).</p>
<p>If a TriBITS package <tt class="docutils literal">&lt;TRIBITS_PACKAGE&gt;</tt> has subpackages (e.g. <tt class="docutils literal">&lt;A&gt;</tt>,
<tt class="docutils literal">&lt;B&gt;</tt>, etc.), then enabling the package is equivalent to setting:</p>
<pre class="literal-block">
-D &lt;Project&gt;_ENABLE_&lt;TRIBITS_PACKAGE&gt;&lt;A&gt;=ON \
-D &lt;Project&gt;_ENABLE_&lt;TRIBITS_PACKAGE&gt;&lt;B&gt;=ON \
 ...
</pre>
<p>However, a TriBITS subpackage will only be enabled if it is not already
disabled either explicitly or implicitly.</p>
<p>NOTE: The CMake cache variable type for all <tt class="docutils literal">XXX_ENABLE_YYY</tt> variables is
actually <tt class="docutils literal">STRING</tt> and not <tt class="docutils literal">BOOL</tt>.  That is because these enable variables
take on the string enum values of <tt class="docutils literal">&quot;ON&quot;</tt>, <tt class="docutils literal">&quot;OFF&quot;</tt>, end empty <tt class="docutils literal">&quot;&quot;</tt>.  An
empty enable means that the TriBITS dependency system is allowed to decide if
an enable should be turned on or off based on various logic.  The CMake GUI
will enforce the values of <tt class="docutils literal">&quot;ON&quot;</tt>, <tt class="docutils literal">&quot;OFF&quot;</tt>, and empty <tt class="docutils literal">&quot;&quot;</tt> but it will
not enforce this if you set the value on the command line or in a SET()
statement in an input <tt class="docutils literal"><span class="pre">`*.cmake</span></tt> options files.  However, setting
<tt class="docutils literal"><span class="pre">-DXXX_ENABLE_YYY=TRUE</span></tt> and <tt class="docutils literal"><span class="pre">-DXXX_ENABLE_YYY=FALSE</span></tt> is allowed and will
be interpreted correctly..</p>
</div>
<div class="section" id="enable-to-test-all-effects-of-changing-a-given-package-s">
<h3><a class="toc-backref" href="#id15">4.3.4&nbsp;&nbsp;&nbsp;Enable to test all effects of changing a given package(s)</a></h3>
<p>To enable an SE package <tt class="docutils literal">&lt;TRIBITS_PACKAGE&gt;</tt> to test it and all of its
down-stream packages, configure with:</p>
<pre class="literal-block">
-D &lt;Project&gt;_ENABLE_&lt;TRIBITS_PACKAGE&gt;=ON \
-D &lt;Project&gt;_ENABLE_ALL_FORWARD_DEP_PACKAGES=ON \
-D &lt;Project&gt;_ENABLE_TESTS=ON \
</pre>
<p>The above set of arguments will result in package <tt class="docutils literal">&lt;TRIBITS_PACKAGE&gt;</tt> and
all packages that depend on <tt class="docutils literal">&lt;TRIBITS_PACKAGE&gt;</tt> to be enabled and have all
of their tests turned on.  Tests will not be enabled in packages that do not
depend on <tt class="docutils literal">&lt;TRIBITS_PACKAGE&gt;</tt> in this case.  This speeds up and robustifies
pre-push testing.</p>
</div>
<div class="section" id="enable-all-packages-with-tests-and-examples">
<h3><a class="toc-backref" href="#id16">4.3.5&nbsp;&nbsp;&nbsp;Enable all packages with tests and examples</a></h3>
<p>To enable all SE packages (and optionally also their tests and examples), add
the configure options:</p>
<pre class="literal-block">
-D &lt;Project&gt;_ENABLE_ALL_PACKAGES=ON \
-D &lt;Project&gt;_ENABLE_TESTS=ON \
</pre>
<p>Specific packages can be disabled with
<tt class="docutils literal"><span class="pre">&lt;Project&gt;_ENABLE_&lt;TRIBITS_PACKAGE&gt;=OFF</span></tt>.  This will also disable all
packages that depend on <tt class="docutils literal">&lt;TRIBITS_PACKAGE&gt;</tt>.</p>
<p>All examples are also enabled by default when setting
<tt class="docutils literal">&lt;Project&gt;_ENABLE_TESTS=ON</tt>.</p>
<p>By default, setting <tt class="docutils literal">&lt;Project&gt;_ENABLE_ALL_PACKAGES=ON</tt> only enables primary
tested (PT) code.  To have this also enable all secondary tested (ST) code,
one must also set <tt class="docutils literal">&lt;Project&gt;_ENABLE_SECONDARY_TESTED_CODE=ON</tt>.</p>
<p>NOTE: If the project is a &quot;meta-project&quot;, then
<tt class="docutils literal">&lt;Project&gt;_ENABLE_ALL_PACKAGES=ON</tt> may not enable <em>all</em> the SE packages
but only the project's primary meta-project packages.  See <a class="reference external" href="../developers_guide/TribitsDevelopersGuide.html#package-dependencies-and-enable-disable-logic">Package
Dependencies and Enable/Disable Logic</a> and <a class="reference external" href="../developers_guide/TribitsDevelopersGuide.html#tribits-dependency-handling-behaviors">TriBITS Dependency Handling
Behaviors</a> for details.</p>
</div>
<div class="section" id="disable-a-package-and-all-its-dependencies">
<h3><a class="toc-backref" href="#id17">4.3.6&nbsp;&nbsp;&nbsp;Disable a package and all its dependencies</a></h3>
<p>To disable an SE package and all of the packages that depend on it, add the
configure options:</p>
<pre class="literal-block">
-D &lt;Project&gt;_ENABLE_&lt;TRIBITS_PACKAGE&gt;=OFF
</pre>
<p>For example:</p>
<pre class="literal-block">
-D &lt;Project&gt;_ENABLE_&lt;PACKAGE_A&gt;=ON \
-D &lt;Project&gt;_ENABLE_ALL_OPTIONAL_PACKAGES=ON \
-D &lt;Project&gt;_ENABLE_&lt;PACKAGE_B&gt;=ON \
</pre>
<p>will enable <tt class="docutils literal">&lt;PACKAGE_A&gt;</tt> and all of the packages that it depends on except
for <tt class="docutils literal">&lt;PACKAGE_B&gt;</tt> and all of its forward dependencies.</p>
<p>If a TriBITS package <tt class="docutils literal">&lt;TRIBITS_PACKAGE&gt;</tt> has subpackages (e.g. <tt class="docutils literal">&lt;A&gt;</tt>,
<tt class="docutils literal">&lt;B&gt;</tt>, etc.), then disabling the package is equivalent to setting:</p>
<pre class="literal-block">
-D &lt;Project&gt;_ENABLE_&lt;TRIBITS_PACKAGE&gt;&lt;A&gt;=OFF \
-D &lt;Project&gt;_ENABLE_&lt;TRIBITS_PACKAGE&gt;&lt;B&gt;=OFF \
...
</pre>
<p>The disable of the subpackage is this case will override any enables.</p>
<p>If a disabled package is a required dependency of some explicitly enabled
downstream package, then the configure will error out if
<tt class="docutils literal">&lt;Project&gt;_DISABLE_ENABLED_FORWARD_DEP_PACKAGES=OFF</tt>.  Otherwise, a WARNING
will be printed and the downstream package will be disabled and configuration
will continue.</p>
</div>
<div class="section" id="remove-all-package-enables-in-the-cache">
<h3><a class="toc-backref" href="#id18">4.3.7&nbsp;&nbsp;&nbsp;Remove all package enables in the cache</a></h3>
<p>To wipe the set of pakage enables in the CMakeCache.txt file so they can be
reset again from scratch, configure with:</p>
<pre class="literal-block">
$ ./-do-confiugre -D &lt;Project&gt;_UNENABLE_ENABLED_PACKAGES=TRUE
</pre>
<p>This option will set to empty '' all package enables, leaving all other cache
variables as they are.  You can then reconfigure with a new set of package
enables for a different set of packages.  This allows you to avoid more
expensive configure time checks and to preserve other cache variables that you
have set and don't want to loose.  For example, one would want to do this to
avoid compiler and TPL checks.</p>
</div>
</div>
<div class="section" id="selecting-compiler-and-linker-options">
<h2><a class="toc-backref" href="#id19">4.4&nbsp;&nbsp;&nbsp;Selecting compiler and linker options</a></h2>
<p>The &lt;Project&gt; TriBITS CMake build system offers the ability to tweak the
built-in CMake approach for setting compiler flags.  When CMake creates the
object file build command for a given source file, it passes in flags to the
compiler in the order:</p>
<pre class="literal-block">
${CMAKE_&lt;LANG&gt;_FLAGS}  ${CMAKE_&lt;LANG&gt;_FLAGS_&lt;CMAKE_BUILD_TYPE&gt;}
</pre>
<p>where <tt class="docutils literal">&lt;LANG&gt;</tt> = <tt class="docutils literal">C</tt>, <tt class="docutils literal">CXX</tt>, or <tt class="docutils literal">Fortran</tt> and <tt class="docutils literal">&lt;CMAKE_BUILD_TYPE&gt;</tt> =
<tt class="docutils literal">DEBUG</tt> or <tt class="docutils literal">RELEASE</tt>.  Note that the options in
<tt class="docutils literal">CMAKE_&lt;LANG&gt;_FLAGS_&lt;CMAKE_BUILD_TYPE&gt;</tt> come after and override those in
<tt class="docutils literal">CMAKE_&lt;LANG&gt;_FLAGS</tt>!  The flags in <tt class="docutils literal">CMAKE_&lt;LANG&gt;_FLAGS</tt> apply to all
build types.  Optimization, debug, and other build-type-specific flags are set
in <tt class="docutils literal">CMAKE_&lt;LANG&gt;_FLAGS_&lt;CMAKE_BUILD_TYPE&gt;</tt>.  CMake automatically provides a
default set of debug and release optimization flags for
<tt class="docutils literal">CMAKE_&lt;LANG&gt;_FLAGS_&lt;CMAKE_BUILD_TYPE&gt;</tt> (e.g. <tt class="docutils literal">CMAKE_CXX_FLAGS_DEBUG</tt> is
typically <tt class="docutils literal"><span class="pre">&quot;-g</span> <span class="pre">-O0&quot;</span></tt> while <tt class="docutils literal">CMAKE_CXX_FLAGS_RELEASE</tt> is typically
<tt class="docutils literal"><span class="pre">&quot;-O3&quot;</span></tt>).  TriBITS provides a means for project and package developers and
users to set and override these compiler flag variables globally and on a
package-by-package basis.  Below, the facilities for manipulating compiler
flags is described.</p>
<p>The &lt;Project&gt; TriBITS CMake build system will set up default compile flags for
GCC ('GNU') in development mode
(i.e. <tt class="docutils literal">&lt;Project&gt;_ENABLE_DEVELOPMENT_MODE=ON</tt>) on order to help produce
portable code.  These flags set up strong warning options and enforce langauge
standards.  In release mode (i.e. <tt class="docutils literal">&lt;Project&gt;_ENABLE_DEVELOPMENT_MODE=ON</tt>),
these flags are not set.  These flags get set internally into the variables
<tt class="docutils literal">CMAKE_&lt;LANG&gt;_FLAGS</tt>.</p>
<ol class="loweralpha simple">
<li>Configuring to build with default debug or release compiler flags:</li>
</ol>
<blockquote>
<p>To build a debug version, pass into 'cmake':</p>
<pre class="literal-block">
-D CMAKE_BUILD_TYPE=DEBUG
</pre>
<p>This will result in debug flags getting passed to the compiler according to
what is set in <tt class="docutils literal">CMAKE_&lt;LANG&gt;_FLAGS_DEBUG</tt>.</p>
<p>To build a release (optimized) version, pass into 'cmake':</p>
<pre class="literal-block">
-D CMAKE_BUILD_TYPE=RELEASE
</pre>
<p>This will result in optimized flags getting passed to the compiler according
to what is in <tt class="docutils literal">CMAKE_&lt;LANG&gt;_FLAGS_RELEASE</tt>.</p>
</blockquote>
<ol class="loweralpha simple" start="2">
<li>Adding arbitrary compiler flags but keeping other default flags:</li>
</ol>
<blockquote>
<p>To append arbitrary compiler flags to <tt class="docutils literal">CMAKE_&lt;LANG&gt;_FLAGS</tt> (which may be
set internally by TriBITS) that apply to all build types, configure with:</p>
<pre class="literal-block">
-D CMAKE_&lt;LANG&gt;_FLAGS=&quot;&lt;EXTRA_COMPILER_OPTIONS&gt;&quot;
</pre>
<p>where <tt class="docutils literal">&lt;EXTRA_COMPILER_OPTIONS&gt;</tt> are your extra compiler options like
<tt class="docutils literal"><span class="pre">&quot;-DSOME_MACRO_TO_DEFINE</span> <span class="pre">-funroll-loops&quot;</span></tt>.  These options will get
appended to (i.e. come after) other internally defined compiler option and
therefore override them.</p>
<p>Options can also be targeted to a specific TriBITS package using:</p>
<pre class="literal-block">
-D &lt;TRIBITS_PACKAGE&gt;_&lt;LANG&gt;_FLAGS=&quot;&lt;EXTRA_COMPILER_OPTIONS&gt;&quot;
</pre>
<p>The package-specific options get appened to those already in
<tt class="docutils literal">CMAKE_&lt;LANG&gt;_FLAGS</tt> and therefore override (but not replace) those set
globally in <tt class="docutils literal">CMAKE_&lt;LANG&gt;_FLAGS</tt> (either internally or by the user in the
cache).</p>
<p>NOTES:</p>
<p>1) Setting <tt class="docutils literal">CMAKE_&lt;LANG&gt;_FLAGS</tt> will override but will not replace any
other internally set flags in <tt class="docutils literal">CMAKE_&lt;LANG&gt;_FLAGS</tt> defined by the
&lt;Project&gt; CMake system because these flags will come after those set
internally.  To get rid of these project/TriBITS default flags, see below.</p>
<p>2) Given that CMake passes in flags in
<tt class="docutils literal">CMAKE_&lt;LANG&gt;_FLAGS_&lt;CMAKE_BUILD_TYPE&gt;</tt> after those in
<tt class="docutils literal">CMAKE_&lt;LANG&gt;_FLAGS</tt>, this means that users setting the
<tt class="docutils literal">CMAKE_&lt;LANG&gt;_FLAGS</tt> and <tt class="docutils literal">&lt;TRIBITS_PACKAGE&gt;_&lt;LANG&gt;_FLAGS</tt> will <em>not</em>
override the flags in <tt class="docutils literal">CMAKE_&lt;LANG&gt;_FLAGS_&lt;CMAKE_BUILD_TYPE&gt;</tt> which come
after on the compile line.  Therefore, setting <tt class="docutils literal">CMAKE_&lt;LANG&gt;_FLAGS</tt> and
<tt class="docutils literal">&lt;TRIBITS_PACKAGE&gt;_&lt;LANG&gt;_FLAGS</tt> should only be used for options that will
not get overridden by the debug or release compiler flags in
<tt class="docutils literal">CMAKE_&lt;LANG&gt;_FLAGS_&lt;CMAKE_BUILD_TYPE&gt;</tt>.  However, setting
<tt class="docutils literal">CMAKE_&lt;LANG&gt;_FLAGS</tt> will work well for adding extra compiler defines
(e.g. -DSOMETHING) for example.</p>
<p>WARNING: Any options that you set through the cache variable
<tt class="docutils literal">CMAKE_&lt;LANG&gt;_FLAGS_&lt;CMAKE_BUILD_TYPE&gt;</tt> will get overridden in the
&lt;Project&gt; CMake system for GNU compilers in development mode so don't try to
manually set CMAKE_&lt;LANG&gt;_FLAGS_&lt;CMAKE_BUILD_TYPE&gt;!  To override those
options, see <tt class="docutils literal">CMAKE_&lt;LANG&gt;_FLAGS_&lt;CMAKE_BUILD_TYPE&gt;_OVERRIDE</tt>.</p>
</blockquote>
<ol class="loweralpha simple" start="3">
<li>Overriding CMAKE_BUILD_TYPE debug/release compiler options:</li>
</ol>
<blockquote>
<p>To override the default CMake-set options in
<tt class="docutils literal">CMAKE_&lt;LANG&gt;_FLAGS_&lt;CMAKE_BUILD_TYPE&gt;</tt>, use:</p>
<pre class="literal-block">
-D CMAKE_&lt;LANG&gt;_FLAGS_&lt;CMAKE_BUILD_TYPE&gt;_OVERRIDE=&quot;&lt;OPTIONS_TO_OVERRIDE&gt;&quot;
</pre>
<p>For example, to default debug options use:</p>
<pre class="literal-block">
-D CMAKE_C_FLAGS_DEBUG_OVERRIDE=&quot;-g -O1&quot; \
-D CMAKE_CXX_FLAGS_DEBUG_OVERRIDE=&quot;-g -O1&quot;
</pre>
<p>and to override default release options use:</p>
<pre class="literal-block">
-D CMAKE_C_FLAGS_RELEASE_OVERRIDE=&quot;-O3 -funroll-loops&quot; \
-D CMAKE_CXX_FLAGS_RELEASE_OVERRIDE=&quot;-03 -fexceptions&quot;
</pre>
<p>NOTES: The TriBITS CMake cache variable
<tt class="docutils literal">CMAKE_&lt;LANG&gt;_FLAGS_&lt;CMAKE_BUILD_TYPE&gt;_OVERRIDE</tt> is used and not
<tt class="docutils literal">CMAKE_&lt;LANG&gt;_FLAGS_&lt;CMAKE_BUILD_TYPE&gt;</tt> because is given a default
internally by CMake and the new varaible is needed to make the override
explicit.</p>
</blockquote>
<ol class="loweralpha simple" start="4">
<li>Appending arbitrary libraries and link flags every executable:</li>
</ol>
<blockquote>
<p>In order to append any set of arbitrary libraries and link flags to your
executables use:</p>
<pre class="literal-block">
-D&lt;Project&gt;_EXTRA_LINK_FLAGS=&quot;&lt;EXTRA_LINK_LIBRARIES&gt;&quot; \
-DCMAKE_EXE_LINKER_FLAGS=&quot;&lt;EXTRA_LINK_FLAGG&gt;&quot;
</pre>
<p>Above, you can pass any type of library and they will always be the last
libraries listed, even after all of the TPLs.</p>
<p>NOTE: This is how you must set extra libraries like Fortran libraries and
MPI libraries (when using raw compilers).  Please only use this variable
as a last resort.</p>
<p>NOTE: You must only pass in libraries in <tt class="docutils literal">&lt;Project&gt;_EXTRA_LINK_FLAGS</tt> and
<em>not</em> arbitrary linker flags.  To pass in extra linker flags that are not
libraries, use the built-in CMake variable <tt class="docutils literal">CMAKE_EXE_LINKER_FLAGS</tt>
instead.  The TriBITS variable <tt class="docutils literal">&lt;Project&gt;_EXTRA_LINK_FLAGS</tt> is badly named
in this respect but the name remains due to backward compatibility
requirements.</p>
</blockquote>
<ol class="loweralpha simple" start="5">
<li>Turning off strong warnings for individual packages:</li>
</ol>
<blockquote>
<p>To turn off strong warnings (for all langauges) for a given TriBITS
package, set:</p>
<pre class="literal-block">
-D &lt;TRIBITS_PACKAGE&gt;_DISABLE_STRONG_WARNINGS=ON
</pre>
<p>This will only affect the compilation of the sources for
<tt class="docutils literal">&lt;TRIBITS_PACKAGES&gt;</tt>, not warnings generated from the header files in
downstream packages or client code.</p>
<p>Note that strong warnings are only enabled by default in development mode
(<tt class="docutils literal"><span class="pre">&lt;Project&gt;_ENABLE_DEVELOPMENT_MODE==ON</span></tt>) but not release mode
(<tt class="docutils literal"><span class="pre">&lt;Project&gt;_ENABLE_DEVELOPMENT_MODE==ON</span></tt>).  A release of &lt;Project&gt; should
therefore not have strong warning options enabled.</p>
</blockquote>
<ol class="loweralpha simple" start="6">
<li>Overriding all (strong warnings and debug/release) compiler options:</li>
</ol>
<blockquote>
<p>To override all compiler options, including both strong warning options
and debug/release options, configure with:</p>
<pre class="literal-block">
-D CMAKE_C_FLAGS=&quot;-O3 -funroll-loops&quot; \
-D CMAKE_CXX_FLAGS=&quot;-03 -fexceptions&quot; \
-D CMAKE_BUILD_TYPE=NONE \
-D &lt;Project&gt;_ENABLE_STRONG_C_COMPILE_WARNINGS=OFF \
-D &lt;Project&gt;_ENABLE_STRONG_CXX_COMPILE_WARNINGS=OFF \
-D &lt;Project&gt;_ENABLE_SHADOW_WARNINGS=OFF \
-D &lt;Project&gt;_ENABLE_COVERAGE_TESTING=OFF \
-D &lt;Project&gt;_ENABLE_CHECKED_STL=OFF \
</pre>
<p>NOTE: Options like <tt class="docutils literal">&lt;Project&gt;_ENABLE_SHADOW_WARNINGS</tt>,
<tt class="docutils literal">&lt;Project&gt;_ENABLE_COVERAGE_TESTING</tt>, and <tt class="docutils literal">&lt;Project&gt;_ENABLE_CHECKED_STL</tt>
do not need to be turned off by default but they are shown above to make it
clear what other CMake cache variables can add compiler and link arguments.</p>
<p>NOTE: By setting <tt class="docutils literal">CMAKE_BUILD_TYPE=NONE</tt>, then <tt class="docutils literal">CMAKE_&lt;LANG&gt;_FLAGS_NONE</tt>
will be empty and therefore the options set in <tt class="docutils literal">CMAKE_&lt;LANG&gt;_FLAGS</tt> will
be all that is passed in.</p>
</blockquote>
<ol class="loweralpha simple" start="7">
<li>Enable and disable shadowing warnings for all &lt;Project&gt; packages:</li>
</ol>
<blockquote>
<p>To enable shadowing warnings for all &lt;Project&gt; packages (that don't already
have them turned on) then use:</p>
<pre class="literal-block">
-D &lt;Project&gt;_ENABLE_SHADOW_WARNINGS=ON
</pre>
<p>To disable shadowing warnings for all &lt;Project&gt; packages (even those that
have them turned on by default) then use:</p>
<pre class="literal-block">
-D &lt;Project&gt;_ENABLE_SHADOW_WARNINGS=OFF
</pre>
<p>NOTE: The default value is empty '' which lets each &lt;Project&gt; package
decide for itself if shadowing warnings will be turned on or off for that
package.</p>
</blockquote>
<ol class="loweralpha simple" start="8">
<li>Removing warnings as errors for CLEANED packages:</li>
</ol>
<blockquote>
<p>To remove the <tt class="docutils literal"><span class="pre">-Werror</span></tt> flag (or some other flag that is set) from being
applied to compile CLEANED packages like Teuchos, set the following when
configuring:</p>
<pre class="literal-block">
-D &lt;Project&gt;_WARNINGS_AS_ERRORS_FLAGS=&quot;&quot;
</pre>
</blockquote>
<ol class="lowerroman simple">
<li>Adding debug symbols to the build:</li>
</ol>
<blockquote>
<p>To get the compiler to add debug symbols to the build, configure with:</p>
<pre class="literal-block">
-D &lt;Project&gt;_ENABLE_DEBUG_SYMBOLS=ON
</pre>
<p>This will add <tt class="docutils literal"><span class="pre">-g</span></tt> on most compilers.  NOTE: One does <strong>not</strong> generally
need to create a fully debug build to get debug symbols on most compilers.</p>
</blockquote>
</div>
<div class="section" id="enabling-support-for-c-11">
<h2><a class="toc-backref" href="#id20">4.5&nbsp;&nbsp;&nbsp;Enabling support for C++11</a></h2>
<p>To enable support for C++11 in packages that support C++11 (either optionally
or required), configure with:</p>
<pre class="literal-block">
-D &lt;Project&gt;_ENABLE_CXX11=ON
</pre>
<p>By default, the system will try to automatically find compiler flags that will
enable C++11 features.  If it finds flags that allow a test C++11 program to
compile, then it will an additional set of configure-time tests to see if
several C++11 features are actually supported by the configured C++ compiler
and support will be disabled if all of these features are not supported.</p>
<p>In order to pre-set and/or override the C++11 compiler flags used, set the
cache variable:</p>
<pre class="literal-block">
-D &lt;Project&gt;_CXX11_FLAGS=&quot;&lt;compiler flags&gt;&quot;
</pre>
</div>
<div class="section" id="enabling-explicit-template-instantiation-for-c">
<h2><a class="toc-backref" href="#id21">4.6&nbsp;&nbsp;&nbsp;Enabling explicit template instantiation for C++</a></h2>
<p>To enable explicit template instantiation for C++ code for packages that
support it, configure with:</p>
<pre class="literal-block">
-D &lt;Project&gt;_ENABLE_EXPLICIT_INSTANTIATION=ON
</pre>
<p>When <tt class="docutils literal">OFF</tt>, all packages that have templated C++ code will use implicit
template instantiation.</p>
<p>Explicit template instantiation can be enabled (<tt class="docutils literal">ON</tt>) or disabled (<tt class="docutils literal">OFF</tt>)
for individual packages with:</p>
<pre class="literal-block">
-D &lt;TRIBITS_PACKAGE&gt;_ENABLE_EXPLICIT_INSTANTIATION=[ON|OFF]
</pre>
<p>The default value for <tt class="docutils literal">&lt;TRIBITS_PACKAGE&gt;_ENABLE_EXPLICIT_INSTANTIATION</tt> is
set by <tt class="docutils literal">&lt;Project&gt;_ENABLE_EXPLICIT_INSTANTIATION</tt>.</p>
<p>For packages that support it, explicit template instantation can massively
reduce the compile times for the C++ code involved.  To see what packages
support explicit instantation just search the CMakeCache.txt file for varibles
with <tt class="docutils literal">ENABLE_EXPLICIT_INSTANTIATION</tt> in the name.</p>
</div>
<div class="section" id="disabling-the-fortran-compiler-and-all-fortran-code">
<h2><a class="toc-backref" href="#id22">4.7&nbsp;&nbsp;&nbsp;Disabling the Fortran compiler and all Fortran code</a></h2>
<p>To disable the Fortran compiler and all &lt;Project&gt; code that depends on Fortran
set:</p>
<pre class="literal-block">
-D &lt;Project&gt;_ENABLE_Fortran=OFF
</pre>
<p>NOTE: The fortran compiler may be disabled automatically by default on
systems like MS Windows.</p>
<p>NOTE: Most Apple Macs do not come with a compatible Fortran compiler by
default so you must turn off Fortran if you don't have a compatible Fortran
compiler.</p>
</div>
<div class="section" id="enabling-runtime-debug-checking">
<h2><a class="toc-backref" href="#id23">4.8&nbsp;&nbsp;&nbsp;Enabling runtime debug checking</a></h2>
<ol class="loweralpha simple">
<li>Enabling &lt;Project&gt; ifdefed runtime debug checking:</li>
</ol>
<blockquote>
<p>To turn on optional ifdefed runtime debug checking, configure with:</p>
<pre class="literal-block">
-D &lt;Project&gt;_ENABLE_DEBUG=ON
</pre>
<p>This will result in a number of ifdefs to be enabled that will perform a
number of runtime checks.  Nearly all of the debug checks in &lt;Project&gt; will
get turned on by default by setting this option.  This option can be set
independent of <tt class="docutils literal">CMAKE_BUILD_TYPE</tt> (which sets the compiler debug/release
options).</p>
<p>NOTES:</p>
<ul class="simple">
<li>The variable <tt class="docutils literal">CMAKE_BUILD_TYPE</tt> controls what compiler options are
passed to the compiler by default while <tt class="docutils literal">&lt;Project&gt;_ENABLE_DEBUG</tt>
controls what defines are set in config.h files that control ifdefed debug
checks.</li>
<li>Setting <tt class="docutils literal"><span class="pre">-DCMAKE_BUILD_TYPE=DEBUG</span></tt> will automatically set the
default <tt class="docutils literal">&lt;Project&gt;_ENABLE_DEBUG=ON</tt>.</li>
</ul>
</blockquote>
<ol class="loweralpha simple" start="2">
<li>Enabling checked STL implementation:</li>
</ol>
<blockquote>
<p>To turn on the checked STL implementation set:</p>
<pre class="literal-block">
-D &lt;Project&gt;_ENABLE_CHECKED_STL=ON
</pre>
<p>NOTES:</p>
<ul class="simple">
<li>By default, this will set -D_GLIBCXX_DEBUG as a compile option for all C++
code.  This only works with GCC currently.</li>
<li>This option is disabled by default because to enable it by default can
cause runtime segfaults when linked against C++ code that was compiled
without -D_GLIBCXX_DEBUG.</li>
</ul>
</blockquote>
</div>
<div class="section" id="configuring-with-mpi-support">
<h2><a class="toc-backref" href="#id24">4.9&nbsp;&nbsp;&nbsp;Configuring with MPI support</a></h2>
<p>To enable MPI support you must minimally set:</p>
<pre class="literal-block">
-D TPL_ENABLE_MPI=ON
</pre>
<p>There is built-in logic to try to find the various MPI components on your
system but you can override (or make suggestions) with:</p>
<pre class="literal-block">
-D MPI_BASE_DIR=&quot;path&quot;
</pre>
<p>(Base path of a standard MPI installation which has the subdirs 'bin', 'libs',
'include' etc.)</p>
<p>or:</p>
<pre class="literal-block">
-D MPI_BIN_DIR=&quot;path1;path2;...;pathn&quot;
</pre>
<p>which sets the paths where the MPI executables (e.g. mpiCC, mpicc, mpirun,
mpiexec) can be found.  By default this is set to <tt class="docutils literal"><span class="pre">${MPI_BASE_DIR}/bin</span></tt> if
<tt class="docutils literal">MPI_BASE_DIR</tt> is set.</p>
<p>The value of <tt class="docutils literal">LD_LIBRARY_PATH</tt> will also automatically be set to
<tt class="docutils literal"><span class="pre">${MPI_BASE_DIR}/lib</span></tt> if it exists.  This is needed for the basic compiler
tests for some MPI implementations that are installed in non-standard
locations.</p>
<p>There are several different different variations for configuring with MPI
support:</p>
<ol class="loweralpha simple">
<li><strong>Configuring build using MPI compiler wrappers:</strong></li>
</ol>
<blockquote>
<p>The MPI compiler wrappers are turned on by default.  There is built-in
logic that will try to find the right compiler wrappers.  However, you can
specifically select them by setting, for example:</p>
<pre class="literal-block">
-D MPI_C_COMPILER:FILEPATH=mpicc \
-D MPI_CXX_COMPILER:FILEPATH=mpic++ \
-D MPI_Fortan_COMPILER:FILEPATH=mpif77
</pre>
<p>which gives the name of the MPI C/C++/Fortran compiler wrapper executable.
If this is just the name of the program it will be looked for in
${MPI_BIN_DIR} and in other standard locations with that name.  If this is
an absolute path, then this will be used as CMAKE_[C,CXX,Fortran]_COMPILER
to compile and link code.</p>
</blockquote>
<ol class="loweralpha simple" start="2">
<li><strong>Configuring to build using raw compilers and flags/libraries:</strong></li>
</ol>
<blockquote>
<p>While using the MPI compiler wrappers as described above is the preferred
way to enable support for MPI, you can also just use the raw compilers and
then pass in all of the other information that will be used to compile and
link your code.</p>
<p>To turn off the MPI compiler wrappers, set:</p>
<pre class="literal-block">
-D MPI_USE_COMPILER_WRAPPERS=OFF
</pre>
<p>You will then need to manually pass in the compile and link lines needed to
compile and link MPI programs.  The compile flags can be set through:</p>
<pre class="literal-block">
-D CMAKE_[C,CXX,Fortran]_FLAGS=&quot;$EXTRA_COMPILE_FLAGS&quot;
</pre>
<p>The link and library flags must be set through:</p>
<pre class="literal-block">
-D &lt;Project&gt;_EXTRA_LINK_FLAGS=&quot;$EXTRA_LINK_FLAGS&quot;
</pre>
<p>Above, you can pass any type of library or other linker flags in and they
will always be the last libraries listed, even after all of the TPLs.</p>
<p>NOTE: A good way to determine the extra compile and link flags for MPI is to
use:</p>
<pre class="literal-block">
export EXTRA_COMPILE_FLAGS=&quot;`$MPI_BIN_DIR/mpiCC --showme:compile`&quot;

export EXTRA_LINK_FLAGS=&quot;`$MPI_BIN_DIR/mpiCC --showme:link`&quot;
</pre>
<p>where <tt class="docutils literal">MPI_BIN_DIR</tt> is set to your MPI installations binary directory.</p>
</blockquote>
<ol class="loweralpha simple" start="3">
<li><strong>Setting up to run MPI programs:</strong></li>
</ol>
<blockquote>
<p>In order to use the ctest program to run MPI tests, you must set the mpi
run command and the options it takes.  The built-in logic will try to find
the right program and options but you will have to override them in many
cases.</p>
<p>MPI test and example executables are passed to CTest <tt class="docutils literal">ADD_TEST()</tt> as:</p>
<pre class="literal-block">
ADD_TEST(
  ${MPI_EXEC} ${MPI_EXEC_PRE_NUMPROCS_FLAGS}
  ${MPI_EXEC_NUMPROCS_FLAG} &lt;NP&gt;
  ${MPI_EXEC_POST_NUMPROCS_FLAGS}
  &lt;TEST_EXECUTABLE_PATH&gt; &lt;TEST_ARGS&gt; )
</pre>
<p>where <tt class="docutils literal">&lt;TEST_EXECUTABLE_PATH&gt;</tt>, <tt class="docutils literal">&lt;TEST_ARGS&gt;</tt>, and <tt class="docutils literal">&lt;NP&gt;</tt> are specific
to the test being run.</p>
<p>The test-independent MPI arguments are:</p>
<pre class="literal-block">
-D MPI_EXEC:FILEPATH=&quot;exec_name&quot;
</pre>
<p>(The name of the MPI run command (e.g. mpirun, mpiexec) that is used to run
the MPI program.  This can be just the name of the program in which case
the full path will be looked for in <tt class="docutils literal">${MPI_BIN_DIR}</tt> as described above.
If it is an absolute path, it will be used without modification.)</p>
<pre class="literal-block">
-D MPI_EXEC_DEFAULT_NUMPROCS=4
</pre>
<p>(The default number of processes to use when setting up and running
MPI test and example executables.  The default is set to '4' and only
needs to be changed when needed or desired.)</p>
<pre class="literal-block">
-D MPI_EXEC_MAX_NUMPROCS=4
</pre>
<p>(The maximum number of processes to allow when setting up and running MPI
test and example executables.  The default is set to '4' but should be set
to the largest number that can be tolerated for the given machine.  Tests
with more processes than this are excluded from the test suite at configure
time.)</p>
<pre class="literal-block">
-D MPI_EXEC_NUMPROCS_FLAG=-np
</pre>
<p>(The command-line option just before the number of processes to use
<tt class="docutils literal">&lt;NP&gt;</tt>.  The default value is based on the name of <tt class="docutils literal">${MPI_EXEC}</tt>, for
example, which is <tt class="docutils literal"><span class="pre">-np</span></tt> for OpenMPI.)</p>
<pre class="literal-block">
-D MPI_EXEC_PRE_NUMPROCS_FLAGS=&quot;arg1;arg2;...;argn&quot;
</pre>
<p>(Other command-line arguments that must come <em>before</em> the numprocs
argument.  The default is empty &quot;&quot;.)</p>
<pre class="literal-block">
-D MPI_EXEC_POST_NUMPROCS_FLAGS=&quot;arg1;arg2;...;argn&quot;
</pre>
<p>(Other command-line arguments that must come <em>after</em> the numprocs
argument.  The default is empty &quot;&quot;.)</p>
<p>NOTE: Multiple arguments listed in <tt class="docutils literal">MPI_EXEC_PRE_NUMPROCS_FLAGS</tt> and
<tt class="docutils literal">MPI_EXEC_POST_NUMPROCS_FLAGS</tt> must be quoted and seprated by <tt class="docutils literal">';'</tt> as
these variables are interpreted as CMake arrays.</p>
</blockquote>
</div>
<div class="section" id="configuring-for-openmp-support">
<h2><a class="toc-backref" href="#id25">4.10&nbsp;&nbsp;&nbsp;Configuring for OpenMP support</a></h2>
<p>To enable OpenMP support, one must set:</p>
<pre class="literal-block">
-D &lt;Project&gt;_ENABLE_OpenMP=ON
</pre>
<p>Note that if you enable OpenMP directly through a compiler option (e.g.,
<tt class="docutils literal"><span class="pre">-fopenmp</span></tt>), you will NOT enable OpenMP inside &lt;Project&gt; source code.</p>
</div>
<div class="section" id="building-shared-libraries">
<h2><a class="toc-backref" href="#id26">4.11&nbsp;&nbsp;&nbsp;Building shared libraries</a></h2>
<p>To configure to build shared libraries, set:</p>
<pre class="literal-block">
-D BUILD_SHARED_LIBS=ON
</pre>
<p>The above option will result in all shared libraries to be build on all
systems (i.e., <tt class="docutils literal">.so</tt> on Unix/Linux systems, <tt class="docutils literal">.dylib</tt> on Mac OS X, and
<tt class="docutils literal">.dll</tt> on Windows systems).</p>
</div>
<div class="section" id="building-static-libraries-and-executables">
<h2><a class="toc-backref" href="#id27">4.12&nbsp;&nbsp;&nbsp;Building static libraries and executables</a></h2>
<p>To build static libraries, turn off the shared library support:</p>
<pre class="literal-block">
-D BUILD_SHARED_LIBS=OFF
</pre>
<p>Some machines, such as the Cray XT5, require static executables.  To build
&lt;Project&gt; executables as static objects, a number of flags must be set:</p>
<pre class="literal-block">
-D BUILD_SHARED_LIBS=OFF \
-D TPL_FIND_SHARED_LIBS=OFF \
-D &lt;Project&gt;_LINK_SEARCH_START_STATIC=ON
</pre>
<p>The first flag tells cmake to build static versions of the &lt;Project&gt;
libraries.  The second flag tells cmake to locate static library versions of
any required TPLs.  The third flag tells the autodetection routines that
search for extra required libraries (such as the mpi library and the gfortran
library for gnu compilers) to locate static versions.</p>
<p>NOTE: The flag <tt class="docutils literal">&lt;Project&gt;_LINK_SEARCH_START_STATIC</tt> is only supported in
cmake version 2.8.5 or higher.  The variable will be ignored in prior releases
of cmake.</p>
</div>
<div class="section" id="enabling-support-for-an-optional-third-party-library-tpl">
<h2><a class="toc-backref" href="#id28">4.13&nbsp;&nbsp;&nbsp;Enabling support for an optional Third-Party Library (TPL)</a></h2>
<p>To enable a given TPL, set:</p>
<pre class="literal-block">
-D TPL_ENABLE_&lt;TPLNAME&gt;=ON
</pre>
<p>where <tt class="docutils literal">&lt;TPLNAME&gt;</tt> = <tt class="docutils literal">Boost</tt>, <tt class="docutils literal">ParMETIS</tt>, etc.</p>
<p>The headers, libraries, and library directories can then be specified with
the input cache variables:</p>
<ul>
<li><p class="first"><tt class="docutils literal">&lt;TPLNAME&gt;_INCLUDE_DIRS:PATH</tt>: List of paths to the header include
directories.  For example:</p>
<pre class="literal-block">
-D Boost_INCLUDE_DIRS=/usr/local/boost/include
</pre>
</li>
<li><p class="first"><tt class="docutils literal">&lt;TPLNAME&gt;_LIBRARY_NAMES:STRING</tt>: List of unadorned library names, in the
order of the link line.  The platform-specific prefixes (e.g.. 'lib') and
postfixes (e.g. '.a', '.lib', or '.dll') will be added automatically by
CMake.  For example:</p>
<pre class="literal-block">
-D BLAS_LIBRARY_NAMES=&quot;blas;gfortran&quot;
</pre>
</li>
<li><p class="first"><tt class="docutils literal">&lt;TPLNAME&gt;_LIBRARY_DIRS:PATH</tt>: The list of directories where the library
files can be found.  For example:</p>
<pre class="literal-block">
-D BLAS_LIBRARY_DIRS=/usr/local/blas
</pre>
</li>
</ul>
<p>The variables <tt class="docutils literal">TPL_&lt;TPLNAME&gt;_INCLUDE_DIRS</tt> and <tt class="docutils literal">TPL_&lt;TPLNAME&gt;_LIBRARIES</tt>
are what are directly used by the TriBITS dependency infrastructure.  These
variables are normally set by the variables <tt class="docutils literal">&lt;TPLNAME&gt;_INCLUDE_DIRS</tt>,
<tt class="docutils literal">&lt;TPLNAME&gt;_LIBRARY_NAMES</tt>, and <tt class="docutils literal">&lt;TPLNAME&gt;_LIBRARY_DIRS</tt> using CMake
<tt class="docutils literal">find</tt> commands but one can always override these by directly setting these
cache variables <tt class="docutils literal">TPL_&lt;TPLNAME&gt;_INCLUDE_DIRS</tt> and
<tt class="docutils literal">TPL_&lt;TPLNAME&gt;_LIBRARIES</tt>, for example, as:</p>
<pre class="literal-block">
-D TPL_Boost_INCLUDE_DIRS=/usr/local/boost/include \
-D TPL_Boost_LIBRARIES=&quot;/user/local/boost/lib/libprogram_options.a;...&quot;
</pre>
<p>This gives the user complete and direct control in specifying exactly what is
used in the build process.  The other variables that start with <tt class="docutils literal">&lt;TPLNAME&gt;_</tt>
are just a convenience to make it easier to specify the location of the
libraries.</p>
<p>In order to allow a TPL that normally requires one or more libraries to ignore
the libraries, one can set <tt class="docutils literal">&lt;TPLNAME&gt;_LIBRARY_NAMES</tt> to empty, for example:</p>
<pre class="literal-block">
-D BLAS_LIBRARY_NAMES=&quot;&quot;
</pre>
<p>Optional package-specific support for a TPL can be turned off by setting:</p>
<pre class="literal-block">
-D &lt;TRIBITS_PACKAGE&gt;_ENABLE_&lt;TPLNAME&gt;=OFF
</pre>
<p>This gives the user full control over what TPLs are supported by which package
independently.</p>
<p>Support for an optional TPL can also be turned on implicitly by setting:</p>
<pre class="literal-block">
-D &lt;TRIBITS_PACKAGE&gt;_ENABLE_&lt;TPLNAME&gt;=ON
</pre>
<p>where <tt class="docutils literal">&lt;TRIBITS_PACKAGE&gt;</tt> is a TriBITS package that has an optional
dependency on <tt class="docutils literal">&lt;TPLNAME&gt;</tt>.  That will result in setting
<tt class="docutils literal"><span class="pre">TPL_ENABLE_&lt;TPLNAME&gt;=ON</span></tt> internally (but not set in the cache) if
<tt class="docutils literal"><span class="pre">TPL_ENABLE_&lt;TPLNAME&gt;=OFF</span></tt> is not already set.</p>
<p>WARNING: Do <em>not</em> try to hack the system and set:</p>
<pre class="literal-block">
TPL_BLAS_LIBRARIES=&quot;-L/some/dir -llib1 -llib2 ...&quot;
</pre>
<p>This is not compatible with proper CMake usage and it not guaranteed
to be supported.</p>
<p>If all the parts of a TPL are not found on an initial configure, then one can
change the variables <tt class="docutils literal">&lt;TPLNAME&gt;_INCLUDE_DIRS</tt>, <tt class="docutils literal">&lt;TPLNAME&gt;_LIBRARY_NAMES</tt>,
and/or <tt class="docutils literal">&lt;TPLNAME&gt;_LIBRARY_DIRS</tt>.  One can do this over and over until the
TPL is found. By reconfiguring, one avoid a complete configure from scrath
which saves time.</p>
</div>
<div class="section" id="disabling-support-for-a-third-party-library-tpl">
<h2><a class="toc-backref" href="#id29">4.14&nbsp;&nbsp;&nbsp;Disabling support for a Third-Party Library (TPL)</a></h2>
<p>Disabling a TPL explicitly can be done using:</p>
<pre class="literal-block">
-D TPL_ENABLE_&lt;TPLNAME&gt;=OFF
</pre>
<p>NOTE: If a disabled TPL is a required dependency of some explicitly enabled
downstream package, then the configure will error out if
&lt;Project&gt;_DISABLE_ENABLED_FORWARD_DEP_PACKAGES=OFF.  Otherwise, a WARNING will
be printed and the downstream package will be disabled and configuration will
continue.</p>
</div>
<div class="section" id="disabling-tentatively-enabled-tpls">
<h2><a class="toc-backref" href="#id30">4.15&nbsp;&nbsp;&nbsp;Disabling tentatively enabled TPLs</a></h2>
<p>To disable a tentatively enabled TPL, set:</p>
<pre class="literal-block">
-D TPL_ENABLE_&lt;TPLNAME&gt;=OFF
</pre>
<p>where <tt class="docutils literal">&lt;TPLNAME&gt;</tt> = <tt class="docutils literal">BinUtils</tt>, <tt class="docutils literal">Boost</tt>, etc.</p>
<p>NOTE: Some TPLs in &lt;Project&gt; are always tentatively enabled (e.g. BinUtils
for C++ stacktracing) and if all of the components for the TPL are found
(e.g. headers and libraries) then support for the TPL will be enabled,
otherwise it will be disabled.  This is to allow as much functionality as
possible to get automatically enabled without the user having to learn about
the TPL, explicitly enable the TPL, and then see if it is supported or not
on the given system.  However, if the TPL is not supported on a given
platform, then it may be better to explicitly disable the TPL (as shown
above) so as to avoid the output from the CMake configure process that shows
the tentatively enabled TPL being processes and then failing to be enabled.
Also, it is possible that the enable process for the TPL may pass, but the
TPL may not work correctly on the given platform.  In this case, one would
also want to explicitly disable the TPL as shown above.</p>
</div>
<div class="section" id="generating-verbose-output">
<h2><a class="toc-backref" href="#id31">4.16&nbsp;&nbsp;&nbsp;Generating verbose output</a></h2>
<p>There are several different ways to generate verbose output to debug problems
when they occur:</p>
<ol class="loweralpha simple" id="project-trace-file-processing">
<li><strong>Trace file processing during configure:</strong></li>
</ol>
<blockquote>
<pre class="literal-block">
-D &lt;Project&gt;_TRACE_FILE_PROCESSING=ON
</pre>
<p>This will cause TriBITS to print out a trace for all of the project's,
repositorie's, and package's files get processed on lines using the prefix
<tt class="docutils literal">File Trace:</tt>.  This shows what files get processed and in what order they
get processed.  To get a clean listing of all the files processed by TriBITS
just grep out the lines starting with <tt class="docutils literal"><span class="pre">--</span> File Trace:</tt>.  This can be
helpful in debugging configure problems without generating too much extra
output.</p>
<p>Note that <a class="reference internal" href="#project-trace-file-processing">&lt;Project&gt;_TRACE_FILE_PROCESSING</a> is set to <tt class="docutils literal">ON</tt> automatically
when <a class="reference internal" href="#project-verbose-configure">&lt;Project&gt;_VERBOSE_CONFIGURE</a>  = <tt class="docutils literal">ON</tt>.</p>
</blockquote>
<ol class="loweralpha simple" id="project-verbose-configure" start="2">
<li><strong>Getting verbose output from TriBITS configure:</strong></li>
</ol>
<blockquote>
<p>To do a complete debug dump for the TriBITS configure process, use:</p>
<pre class="literal-block">
-D &lt;Project&gt;_VERBOSE_CONFIGURE=ON
</pre>
<p>This produces a <em>lot</em> of output but can be very useful when debugging
configuration problems.</p>
<p>To just dump the package and TPL dependencies, use:</p>
<pre class="literal-block">
-D &lt;Project&gt;_DUMP_PACKAGE_DEPENDENCIES=ON
</pre>
<p>To just dump the link libraries for each library and executable created,
use:</p>
<pre class="literal-block">
-D &lt;Project&gt;_DUMP_LINK_LIBS=ON
</pre>
<p>Of course <tt class="docutils literal">&lt;Project&gt;_DUMP_PACKAGE_DEPENDENCIES</tt> and
<tt class="docutils literal">&lt;Project&gt;_DUMP_LINK_LIBS</tt> can be used together.  Also, note that
<tt class="docutils literal">&lt;Project&gt;_DUMP_PACKAGE_DEPENDENCIES</tt> and <tt class="docutils literal">&lt;Project&gt;_DUMP_LINK_LIBS</tt>
both default t <tt class="docutils literal">ON</tt> when <tt class="docutils literal">&lt;Project&gt;_VERBOSE_CONFIGURE=ON</tt> on the first
configure.</p>
</blockquote>
<ol class="loweralpha simple" start="3">
<li><strong>Getting verbose output from the makefile:</strong></li>
</ol>
<blockquote>
<pre class="literal-block">
-D CMAKE_VERBOSE_MAKEFILE=TRUE
</pre>
<p>NOTE: It is generally better to just pass in <tt class="docutils literal">VERBOSE=</tt> when directly
calling <tt class="docutils literal">make</tt> after configuration is finihsed.  See <a class="reference internal" href="#building-with-verbose-output-without-reconfiguring">Building with
verbose output without reconfiguring</a>.</p>
</blockquote>
<ol class="loweralpha simple" start="4">
<li><strong>Getting very verbose output from configure:</strong></li>
</ol>
<blockquote>
<pre class="literal-block">
-D &lt;Project&gt;_VERBOSE_CONFIGURE=ON --debug-output --trace
</pre>
<p>NOTE: This will print a complete stack trace to show exactly where you are.</p>
</blockquote>
</div>
<div class="section" id="enabling-disabling-deprecated-warnings">
<h2><a class="toc-backref" href="#id32">4.17&nbsp;&nbsp;&nbsp;Enabling/disabling deprecated warnings</a></h2>
<p>To turn off all deprecated warnings, set:</p>
<pre class="literal-block">
-D &lt;Project&gt;_SHOW_DEPRECATED_WARNINGS=OFF
</pre>
<p>This will disable, by default, all deprecated warnings in packages in
&lt;Project&gt;.  By default, deprecated warnings are enabled.</p>
<p>To enable/disable deprecated warnings for a single &lt;Project&gt; package, set:</p>
<pre class="literal-block">
-D &lt;TRIBITS_PACKAGE&gt;_SHOW_DEPRECATED_WARNINGS=OFF
</pre>
<p>This will override the global behavior set by
<tt class="docutils literal">&lt;Project&gt;_SHOW_DEPRECATED_WARNINGS</tt> for individual package
<tt class="docutils literal">&lt;TRIBITS_PACKAGE&gt;</tt>.</p>
</div>
<div class="section" id="disabling-deprecated-code">
<h2><a class="toc-backref" href="#id33">4.18&nbsp;&nbsp;&nbsp;Disabling deprecated code</a></h2>
<p>To actually disable and remove deprecated code from being included in
compilation, set:</p>
<pre class="literal-block">
-D &lt;Project&gt;_HIDE_DEPRECATED_CODE=ON
</pre>
<p>and a subset of deprecated code will actually be removed from the build.  This
is to allow testing of downstream client code that might otherwise ignore
deprecated warnings.  This allows one to certify that a downstream client code
is free of calling deprecated code.</p>
<p>To hide deprecated code for a single &lt;Project&gt; package set:</p>
<pre class="literal-block">
-D &lt;TRIBITS_PACKAGE&gt;_HIDE_DEPRECATED_CODE=ON
</pre>
<p>This will override the global behavior set by
<tt class="docutils literal">&lt;Project&gt;_HIDE_DEPRECATED_CODE</tt> for individual package
<tt class="docutils literal">&lt;TRIBITS_PACKAGE&gt;</tt>.</p>
</div>
<div class="section" id="outputting-package-dependency-information">
<h2><a class="toc-backref" href="#id34">4.19&nbsp;&nbsp;&nbsp;Outputting package dependency information</a></h2>
<p>To generate the various XML and HTML package dependency files, one can set the
output directory when configuring using:</p>
<pre class="literal-block">
-D &lt;Project&gt;_DEPS_DEFAULT_OUTPUT_DIR:FILEPATH=&lt;SOME_PATH&gt;
</pre>
<p>This will generate, by default, the output files
&lt;Project&gt;PackageDependencies.xml, &lt;Project&gt;PackageDependenciesTable.html, and
CDashSubprojectDependencies.xml.</p>
<p>The filepath for &lt;Project&gt;PackageDependencies.xml can be overridden using:</p>
<pre class="literal-block">
-D &lt;Project&gt;_DEPS_XML_OUTPUT_FILE:FILEPATH=&lt;SOME_FILE_PATH&gt;
</pre>
<p>The filepath for &lt;Project&gt;PackageDependenciesTable.html can be overridden
using:</p>
<pre class="literal-block">
-D &lt;Project&gt;_DEPS_HTML_OUTPUT_FILE:FILEPATH=&lt;SOME_FILE_PATH&gt;
</pre>
<p>The filepath for CDashSubprojectDependencies.xml can be overridden using:</p>
<pre class="literal-block">
-D &lt;Project&gt;_CDASH_DEPS_XML_OUTPUT_FILE:FILEPATH=&lt;SOME_FILE_PATH&gt;
</pre>
<p>NOTES:</p>
<ul class="simple">
<li>One must start with a clean CMake cache for all of these defaults to work.</li>
<li>The files &lt;Project&gt;PackageDependenciesTable.html and
CDashSubprojectDependencies.xml will only get generated if support for
Python is enabled.</li>
</ul>
</div>
<div class="section" id="enabling-different-test-categories">
<h2><a class="toc-backref" href="#id35">4.20&nbsp;&nbsp;&nbsp;Enabling different test categories</a></h2>
<p>To turn on a set a given set of tests by test category, set:</p>
<pre class="literal-block">
-D &lt;Project&gt;_TEST_CATEGORIES=&quot;&lt;CATEGORY0&gt;;&lt;CATEGORY1&gt;;...&quot;
</pre>
<p>Valid categories include <tt class="docutils literal">BASIC</tt>, <tt class="docutils literal">CONTINUOUS</tt>, <tt class="docutils literal">NIGHTLY</tt>, <tt class="docutils literal">WEEKLY</tt>
and <tt class="docutils literal">PERFORMANCE</tt>.  <tt class="docutils literal">BASIC</tt> tests get built and run for pre-push testing,
CI testing, and nightly testing.  <tt class="docutils literal">CONTINUOUS</tt> tests are for post-push
testing and nightly testing.  <tt class="docutils literal">NIGHTLY</tt> tests are for nightly testing only.
<tt class="docutils literal">WEEKLY</tt> tests are for more expensive tests that are run approximately
weekly.  <tt class="docutils literal">PERFORMANCE</tt> tests a special category used only for performance
testing.</p>
</div>
<div class="section" id="disabling-specific-tests">
<h2><a class="toc-backref" href="#id36">4.21&nbsp;&nbsp;&nbsp;Disabling specific tests</a></h2>
<p>Any TriBTS added ctest test (i.e. listed in <tt class="docutils literal">ctest <span class="pre">-N</span></tt>) can be disabled at
configure time by setting:</p>
<pre class="literal-block">
-D &lt;fullTestName&gt;_DISABLE=ON
</pre>
<p>where <tt class="docutils literal">&lt;fulltestName&gt;</tt> must exactly match the test listed out by <tt class="docutils literal">ctest
<span class="pre">-N</span></tt>.  Of course specific tests can also be excluded from <tt class="docutils literal">ctest</tt> using the
<tt class="docutils literal"><span class="pre">-E</span></tt> argument.</p>
</div>
<div class="section" id="trace-test-addition-or-exclusion">
<h2><a class="toc-backref" href="#id37">4.22&nbsp;&nbsp;&nbsp;Trace test addition or exclusion</a></h2>
<p>To see what tests get added and see those that don't get added for various
reasons, configure with:</p>
<pre class="literal-block">
-D &lt;Project&gt;_TRACE_ADD_TEST=ON
</pre>
<p>That will print one line per show that the test got added and if not then why
the test was not added (i.e. due to the test's <tt class="docutils literal">COMM</tt>, <tt class="docutils literal">NUM_MPI_PROCS</tt>,
<tt class="docutils literal">CATEGORIES</tt>, <tt class="docutils literal">HOST</tt>, <tt class="docutils literal">XHOST</tt>, <tt class="docutils literal">HOSTTYPE</tt>, or <tt class="docutils literal">XHOSTTYPE</tt>
arguments).</p>
</div>
<div class="section" id="setting-test-timeouts-at-configure-time">
<h2><a class="toc-backref" href="#id38">4.23&nbsp;&nbsp;&nbsp;Setting test timeouts at configure time</a></h2>
<p>A maximum default time limit for any single test can be set at configure time
by setting:</p>
<pre class="literal-block">
-D DART_TESTING_TIMEOUT=&lt;maxSeconds&gt;
</pre>
<p>where <tt class="docutils literal">&lt;maxSeconds&gt;</tt> is the number of wall-clock seconds.  By default there
is no timeout limit so it is a good idea to set some limit just so tests don't
hang and run forever.  When an MPI code has a defect, it can easily hang
forever until it is manually killed.  If killed, CTest will kill all of this
child processes correctly.</p>
<p>NOTES:</p>
<ul class="simple">
<li>Be careful not set the timeout too low since if a machine becomes loaded
tests can take longer to run and may result in timeouts that would not
otherwise occur.</li>
<li>Individual tests can have there timeout limit increased on a test-by-test
basis internally in the project's CMakeLists.txt files (see the <tt class="docutils literal">TIMEOUT</tt>
argument for <tt class="docutils literal">TRIBITS_ADD_TEST()</tt> and <tt class="docutils literal">TRIBITS_ADD_ADVANCED_TEST()</tt>).</li>
<li>To set or override the test timeout limit at runtime, see <a class="reference internal" href="#overridding-test-timeouts">Overridding test
timeouts</a>.</li>
</ul>
</div>
<div class="section" id="scaling-test-timeouts-at-configure-time">
<span id="project-scale-test-timeout-testing-timeout"></span><h2><a class="toc-backref" href="#id39">4.24&nbsp;&nbsp;&nbsp;Scaling test timeouts at configure time</a></h2>
<p>The global default test timeout <tt class="docutils literal">DART_TESTING_TIMEOUT</tt> as well as all of the
timeouts for the individual tests that have their own timeout set (through the
<tt class="docutils literal">TIMEOUT</tt> argument for each individual test) can be scaled by a constant
factor <tt class="docutils literal">&lt;testTimeoutScaleFactor&gt;</tt> by configuring with:</p>
<pre class="literal-block">
-D &lt;Project&gt;_SCALE_TEST_TIMEOUT=&lt;testTimeoutScaleFactor&gt;
</pre>
<p>Here, <tt class="docutils literal">&lt;testTimeoutScaleFactor&gt;</tt> can be an integral number like <tt class="docutils literal">5</tt> or can
be fractional number like <tt class="docutils literal">1.5</tt>.</p>
<p>This feature is generally used to compensate for slower machines or overloaded
test machines and therefore only scaling factors greater than 1 are to be
used.  The primary use case for this feature is to add large scale factors
(e.g. <tt class="docutils literal">40</tt> to <tt class="docutils literal">100</tt>) to compensate for running test using valgrind (see
<a class="reference internal" href="#running-memory-checking">Running memory checking</a>).</p>
<p>NOTES:</p>
<ul class="simple">
<li>When scaling the timeouts, the timeout is first truncated to integral
seconds so an original timeout like <tt class="docutils literal">200.5</tt> will be truncated to <tt class="docutils literal">200</tt>
before it gets scaled.</li>
<li>Only the first fractional digit is used so <tt class="docutils literal">1.57</tt> is truncated to <tt class="docutils literal">1.5</tt>
before scaling the test timeouts.</li>
<li>The cache value of the variable <tt class="docutils literal">DART_TESTING_TIMEOUT</tt> is not changed in
the CMake cache file.  Only the value of the timeout written into the
DartConfiguration.tcl file will be scaled.</li>
</ul>
</div>
<div class="section" id="enabling-support-for-coverage-testing">
<h2><a class="toc-backref" href="#id40">4.25&nbsp;&nbsp;&nbsp;Enabling support for coverage testing</a></h2>
<p>To turn on support for coverage testing set:</p>
<pre class="literal-block">
-D &lt;Project&gt;_ENABLE_COVERAGE_TESTING=ON
</pre>
<p>This will set compile and link options -fprofile-arcs -ftest-coverage for GCC.
Use 'make dashboard' (see below) to submit coverage results to CDash</p>
</div>
<div class="section" id="viewing-configure-options-and-documentation">
<h2><a class="toc-backref" href="#id41">4.26&nbsp;&nbsp;&nbsp;Viewing configure options and documentation</a></h2>
<ol class="loweralpha simple">
<li>Viewing available configure-time options with documentation:</li>
</ol>
<blockquote>
<pre class="literal-block">
$ cd $BUILD_DIR
$ rm -rf CMakeCache.txt CMakeFiles/
$ cmake -LAH -D &lt;Project&gt;_ENABLE_ALL_PACKAGES=ON \
  $SOURCE_BASE
</pre>
<p>You can also just look at the text file CMakeCache.txt after configure which
gets created in the build directory and has all of the cache variables and
documentation.</p>
</blockquote>
<ol class="loweralpha simple" start="2">
<li>Viewing available configure-time options without documentation:</li>
</ol>
<blockquote>
<pre class="literal-block">
$ cd $BUILD_DIR
$ rm -rf CMakeCache.txt CMakeFiles/
$ cmake -LA &lt;SAME_AS_ABOVE&gt; $SOURCE_BASE
</pre>
</blockquote>
<ol class="loweralpha simple" start="3">
<li>Viewing current values of cache variables:</li>
</ol>
<blockquote>
<pre class="literal-block">
$ cmake -LA $SOURCE_BASE
</pre>
<p>or just examine and grep the file CMakeCache.txt.</p>
</blockquote>
</div>
<div class="section" id="enabling-extra-repositories-with-add-on-packages">
<h2><a class="toc-backref" href="#id42">4.27&nbsp;&nbsp;&nbsp;Enabling extra repositories with add-on packages:</a></h2>
<p id="project-extra-repositories">To configure &lt;Project&gt; with an extra set of packages in extra TriBITS
repositories, configure with:</p>
<pre class="literal-block">
-D&lt;Project&gt;_EXTRA_REPOSITORIES=&quot;&lt;REPO0&gt;,&lt;REPO1&gt;,...&quot;
</pre>
<p>Here, <tt class="docutils literal">&lt;REPOi&gt;</tt> is the name of an extra repository that typically has been
cloned under the main &lt;Project&gt; source directory as:</p>
<pre class="literal-block">
&lt;Project&gt;/&lt;REPOi&gt;/
</pre>
<p>For example, to add the packages from SomeExtraRepo one would configure as:</p>
<pre class="literal-block">
$ cd $SOURCE_BASE_DIR
$ git clone some_url.com/some/dir/SomeExtraRepo
$ cd $BUILD_DIR
$ ./do-configure -D&lt;Project&gt;_EXTRA_REPOSITORIES=SomeExtraRepo \
   [Other Options]
</pre>
<p>After that, all of the extra packages defined in <tt class="docutils literal">SomeExtraRepo</tt> will appear
in the list of official &lt;Project&gt; packages and you are free to enable any of
the defined add-on packages that you would like just like any other &lt;Project&gt;
package.</p>
<p>NOTE: If <tt class="docutils literal">&lt;Project&gt;_EXTRAREPOS_FILE</tt> and
<tt class="docutils literal">&lt;Project&gt;_ENABLE_KNOWN_EXTERNAL_REPOS_TYPE</tt> are specified then the list of
extra repositories in <tt class="docutils literal">&lt;Project&gt;_EXTRA_REPOSITORIES</tt> must be a subset and in
the same order as the list extra repos read in from the file specified by
<a class="reference internal" href="#project-extrarepos-file">&lt;Project&gt;_EXTRAREPOS_FILE</a>.</p>
</div>
<div class="section" id="enabling-extra-repositories-through-a-file">
<h2><a class="toc-backref" href="#id43">4.28&nbsp;&nbsp;&nbsp;Enabling extra repositories through a file</a></h2>
<p id="project-extrarepos-file">In order to provide the list of extra TriBIITS repositories containing add-on
packages from a file, configure with:</p>
<pre class="literal-block">
-D&lt;Project&gt;_EXTRAREPOS_FILE:FILEPATH=&lt;EXTRAREPOSFILE&gt; \
-D&lt;Project&gt;_ENABLE_KNOWN_EXTERNAL_REPOS_TYPE=Continuous
</pre>
<p>Specifing extra repositories through an extra repos file allows greater
flexibility in the specification of extra repos.  This is not helpful for a
basic configure of the project but is useful in automated testing using the
<tt class="docutils literal">TribitsCTestDriverCore.cmake</tt> script and the <tt class="docutils literal"><span class="pre">checkin-test.py</span></tt> script.</p>
<p>The valid values of <tt class="docutils literal">&lt;Project&gt;_ENABLE_KNOWN_EXTERNAL_REPOS_TYPE</tt> include
<tt class="docutils literal">Continuous</tt>, <tt class="docutils literal">Nightly</tt>, and <tt class="docutils literal">Experimental</tt>.  Only repositories listed
in the file <tt class="docutils literal">&lt;EXTRAREPOSFILE&gt;</tt> that match this type will be included.  Note
that <tt class="docutils literal">Nightly</tt> matches <tt class="docutils literal">Continuous</tt> and <tt class="docutils literal">Experimental</tt> matches
<tt class="docutils literal">Nightly</tt> and <tt class="docutils literal">Continuous</tt> and therefore includes all repos by default.</p>
<p>If <tt class="docutils literal">&lt;Project&gt;_IGNORE_MISSING_EXTRA_REPOSITORIES</tt> is set to <tt class="docutils literal">TRUE</tt>, then
any extra repositories selected who's directory is missing will be ignored.
This is useful when the list of extra repos that a given developers develops
or tests with is variable and one just wants TriBITS to pick up the list of
existing repos automatically.</p>
<p>If the file <tt class="docutils literal"><span class="pre">&lt;projectDir&gt;/cmake/ExtraRepositoriesList.cmake</span></tt> exists, then it
is used as the default value for <tt class="docutils literal">&lt;Project&gt;_EXTRAREPOS_FILE</tt>.  However, the
default value for <tt class="docutils literal">&lt;Project&gt;_ENABLE_KNOWN_EXTERNAL_REPOS_TYPE</tt> is empty so
no extra repostories are defined by default unless
<tt class="docutils literal">&lt;Project&gt;_ENABLE_KNOWN_EXTERNAL_REPOS_TYPE</tt> is specifically set to one of
the allowed values.</p>
</div>
<div class="section" id="reconfiguring-completely-from-scratch">
<h2><a class="toc-backref" href="#id44">4.29&nbsp;&nbsp;&nbsp;Reconfiguring completely from scratch</a></h2>
<p>To reconfigure from scratch, one needs to delete the the <tt class="docutils literal">CMakeCache.txt</tt>
and base-level <tt class="docutils literal">CMakeFiles/</tt> directory, for example, as:</p>
<pre class="literal-block">
$ rm -rf CMakeCache.txt CMakeFiles/
$ ./do-configure [options]
</pre>
<p>Removing the <tt class="docutils literal">CMakeCache.txt</tt> file is often needed when removing variables
from the configure line since they are already in the cache.  Removing the
<tt class="docutils literal">CMakeFiles/</tt> directories is needed if there are changes in some CMake
modules or the CMake version itself.  However, usually removing just the
top-level <tt class="docutils literal">CMakeCache.txt</tt> and <tt class="docutils literal">CMakeFiles/</tt> directory is enough to
guarantee a clean reconfigure from a dirty build directory.</p>
<p>If one really wants a clean slate, then try:</p>
<pre class="literal-block">
$ rm -rf `ls | grep -v do-configure`
$ ./do-configure [options]
</pre>
<p>WARNING: Later versions of CMake (2.8.10.2+) require that you remove the
top-level <tt class="docutils literal">CMakeFiles/</tt> directory whenever you remove the <tt class="docutils literal">CMakeCache.txt</tt>
file.</p>
</div>
<div class="section" id="viewing-configure-errors">
<h2><a class="toc-backref" href="#id45">4.30&nbsp;&nbsp;&nbsp;Viewing configure errors</a></h2>
<p>To view various configure errors, read the file:</p>
<pre class="literal-block">
$BUILD_BASE_DIR/CMakeFiles/CMakeError.log
</pre>
<p>This file contains detailed output from try-compile commands, Fortran/C name
managling determination, and other CMake-specific information.</p>
</div>
<div class="section" id="adding-configure-timers">
<h2><a class="toc-backref" href="#id46">4.31&nbsp;&nbsp;&nbsp;Adding configure timers</a></h2>
<p>To add timers to various configure steps, configure with:</p>
<pre class="literal-block">
-D &lt;Project&gt;_ENABLE_CONFIGURE_TIMING=ON
</pre>
<p>This will do baulk timing for the major configure steps which is independent
of the number of packages in the project.</p>
<p>To additionally add timing for the configure of individual packages, configure
with:</p>
<pre class="literal-block">
-D &lt;Project&gt;_ENABLE_CONFIGURE_TIMING=ON \
-D &lt;Project&gt;_ENABLE_PACKAGE_CONFIGURE_TIMING=ON
</pre>
<p>If you are configuring a large number of packages (perhaps by including a lot
of add-on packages in extra repos) then you might not want to enable
package-by-package timing since it can add some significant overhead to the
configure times.</p>
<p>If you just want to time individual packages instead, you can enable that
with:</p>
<pre class="literal-block">
-D &lt;Project&gt;_ENABLE_CONFIGURE_TIMING=ON \
-D &lt;TRIBITS_PACKAGE_0&gt;_PACKAGE_CONFIGURE_TIMING=ON \
-D &lt;TRIBITS_PACKAGE_1&gt;_PACKAGE_CONFIGURE_TIMING=ON \
...
</pre>
<p>NOTES:</p>
<ul class="simple">
<li>This requires that you are running on a Linux/Unix system that has the
standard shell command <tt class="docutils literal">date</tt>.  CMake does not have built-in timing
functions so this system command needs to be used instead.  This will report
timings to 0.001 seconds but note that the overall configure time will go up
due to the increased overhead of calling <tt class="docutils literal">date</tt> as a process shell
command.</li>
<li>'''WARNING:''' Because this feature has to call the <tt class="docutils literal">data</tt> using CMake's
<tt class="docutils literal">EXECUTE_PROCESS()</tt> command, it can be expensive.  Therefore, this should
really only be turned on for large projects (where the extra overhead is
small) or for smaller projects for extra informational purposes.</li>
</ul>
</div>
<div class="section" id="generating-export-files">
<h2><a class="toc-backref" href="#id47">4.32&nbsp;&nbsp;&nbsp;Generating export files</a></h2>
<p>The project &lt;Project&gt; can generate export files for external CMake projects or
external Makefile projects.  These export files provide the lists of
libraries, include directories, compilers and compiler options, etc.</p>
<p>To configure to generate CMake export files for the project, configure with:</p>
<pre class="literal-block">
-D &lt;Project&gt;_ENABLE_INSTALL_CMAKE_CONFIG_FILES=ON
</pre>
<p>This will generate the file <tt class="docutils literal">&lt;Project&gt;Config.cmake</tt> for the project and the
files <tt class="docutils literal">&lt;Package&gt;Config.cmake</tt> for each enabled package in the build tree.
In addition, this will install versions of these files into the install tree.</p>
<p>To confiugre Makefile export files, configure with:</p>
<pre class="literal-block">
-D &lt;Project&gt;_ENABLE_EXPORT_MAKEFILES=ON
</pre>
<p>which will generate the file <tt class="docutils literal"><span class="pre">Makefile.export.&lt;Project&gt;</span></tt> for the project and
the files <tt class="docutils literal"><span class="pre">Makefile.export.&lt;Package&gt;</span></tt> for each enabled package in the build
tree.  In addition, this will install versions of these files into the install
tree.</p>
<p>The list of export files generated can be reduced by specifying the exact list
of packages the files are requested for with:</p>
<pre class="literal-block">
-D &lt;Project&gt;_GENERATE_EXPORT_FILES_FOR_ONLY_LISTED_SE_PACKAGES=&quot;&lt;pkg0&gt;;&lt;pkg1&gt;&quot;
</pre>
<p>NOTES:</p>
<ul class="simple">
<li>Only enabled packages will have their export files generated.</li>
<li>One would only want to limit the export files generated for very large
projects where the cost my be high for doing so.</li>
</ul>
</div>
<div class="section" id="generating-a-project-repo-version-file">
<h2><a class="toc-backref" href="#id48">4.33&nbsp;&nbsp;&nbsp;Generating a project repo version file</a></h2>
<p>In development mode working with local git repos for the project sources, on
can generate a &lt;Project&gt;RepoVersion.txt file which lists all of the repos and
their current versions using:</p>
<pre class="literal-block">
-D &lt;Project&gt;_GENERATE_REPO_VERSION_FILE=ON
</pre>
<p>This will cause a &lt;Project&gt;RepoVersion.txt file to get created in the binary
directory, get installed in the install directory, and get included in the
source distribution tarball.</p>
</div>
<div class="section" id="cmake-configure-time-development-mode-and-debug-checking">
<h2><a class="toc-backref" href="#id49">4.34&nbsp;&nbsp;&nbsp;CMake configure-time development mode and debug checking</a></h2>
<p>To turn off CMake configure-time development-mode checking, set:</p>
<pre class="literal-block">
-D &lt;Project&gt;_ENABLE_DEVELOPMENT_MODE=OFF
</pre>
<p>This turns off a number of CMake configure-time checks for the &lt;Project&gt;
TriBITS/CMake files including checking the package dependencies.  These checks
can be expensive and may also not be appropriate for a tarball release of the
software.  For a release of &lt;Project&gt; this option is set OFF by default.</p>
<p>One of the CMake configure-time debug-mode checks performed as part of
<tt class="docutils literal">&lt;Project&gt;_ENABLE_DEVELOPMENT_MODE=ON</tt> is to assert the existence of TriBITS
package directories.  In development mode, the failure to find a package
directory is usually a programming error (i.e. a miss-spelled package
directory name).  But in a tarball release of the project, package directories
may be purposefully missing (see <cite>Creating a tarball of the source tree</cite>) and
must be ignored.  When building from a reduced tarball created from the
development sources, set:</p>
<pre class="literal-block">
-D &lt;Project&gt;_ASSERT_MISSING_PACKAGES=OFF
</pre>
<p>Setting this off will cause the TriBITS CMake configure to simply ignore any
missing packages and turn off all dependencies on these missing packages.</p>
</div>
</div>
<div class="section" id="building-makefile-generator">
<h1><a class="toc-backref" href="#id50">5&nbsp;&nbsp;&nbsp;Building (Makefile generator)</a></h1>
<p>This section described building using the default CMake Makefile generator.
TriBITS supports other CMake generators such as Visual Studio on Windows,
XCode on Macs, and Eclipe project files but using those build systems are not
documented here.</p>
<div class="section" id="building-all-targets">
<h2><a class="toc-backref" href="#id51">5.1&nbsp;&nbsp;&nbsp;Building all targets</a></h2>
<p>To build all targets use:</p>
<pre class="literal-block">
$ make [-jN]
</pre>
<p>where <tt class="docutils literal">N</tt> is the number of processes to use (i.e. 2, 4, 16, etc.) .</p>
</div>
<div class="section" id="discovering-what-targets-are-available-to-build">
<h2><a class="toc-backref" href="#id52">5.2&nbsp;&nbsp;&nbsp;Discovering what targets are available to build</a></h2>
<p>CMake generates Makefiles with a 'help' target!  To see the targets at the
current directory level type:</p>
<pre class="literal-block">
$ make help
</pre>
<p>NOTE: In general, the <tt class="docutils literal">help</tt> target only prints targets in the current
directory, not targets in subdirectories.  These targets can include object
files and all, anything that CMake defines a target for in the current
directory.  However, running <tt class="docutils literal">make help</tt> it from the base build directory
will print all major targets in the project (i.e. libraries, executables,
etc.) but not minor targets like object files.  Any of the printed targets can
be used as a target for <tt class="docutils literal">make <span class="pre">&lt;some-target&gt;</span></tt>.  This is super useful for just
building a single object file, for example.</p>
</div>
<div class="section" id="building-all-of-the-targets-for-a-package">
<h2><a class="toc-backref" href="#id53">5.3&nbsp;&nbsp;&nbsp;Building all of the targets for a package</a></h2>
<p>To build only the targets for a given TriBITS package, one can use:</p>
<pre class="literal-block">
$ make &lt;TRIBITS_PACKAGE&gt;_all
</pre>
<p>or:</p>
<pre class="literal-block">
$ cd packages/&lt;TRIBITS_PACKAGE&gt;
$ make
</pre>
<p>This will build only the targets for TriBITS package <tt class="docutils literal">&lt;TRIBITS_PACKAGE&gt;</tt> and
its required upstream targets.</p>
</div>
<div class="section" id="building-all-of-the-libraries-for-a-package">
<h2><a class="toc-backref" href="#id54">5.4&nbsp;&nbsp;&nbsp;Building all of the libraries for a package</a></h2>
<p>To build only the libraries for given TriBITS package, use:</p>
<pre class="literal-block">
$ make &lt;TRIBITS_PACKAGE&gt;_libs
</pre>
</div>
<div class="section" id="building-all-of-the-libraries-for-all-enabled-packages">
<h2><a class="toc-backref" href="#id55">5.5&nbsp;&nbsp;&nbsp;Building all of the libraries for all enabled packages</a></h2>
<p>To build only the libraries for all enabled TriBITS packages, use:</p>
<pre class="literal-block">
$ make libs
</pre>
<p>NOTE: This target depends on the <tt class="docutils literal">&lt;PACKAGE&gt;_libs</tt> targets for all of the
enabled <tt class="docutils literal">&lt;Project&gt;</tt> packages.  You can also use the target name
<tt class="docutils literal">'&lt;Project&gt;_libs</tt>.</p>
</div>
<div class="section" id="building-a-single-object-file">
<h2><a class="toc-backref" href="#id56">5.6&nbsp;&nbsp;&nbsp;Building a single object file</a></h2>
<p>To build just a single object file (i.e. to debug a compile problem), first,
look for the target name for the object file build based on the source file,
for example for the source file <tt class="docutils literal">SomeSourceFile.cpp</tt>, use:</p>
<pre class="literal-block">
$ make help | grep SomeSourceFile
</pre>
<p>The above will return a target name like:</p>
<pre class="literal-block">
... SomeSourceFile.o
</pre>
<p>To find the name of the actual object file, do:</p>
<pre class="literal-block">
$ find . -name &quot;*SomeSourceFile*.o&quot;
</pre>
<p>that will return something like:</p>
<pre class="literal-block">
./CMakeFiles/&lt;source-dir-path&gt;.dir/SomeSourceFile.cpp.o
</pre>
<p>(but this file location and name depends on the source directory structure,
the version of CMake, and other factors).  Use the returned name (exactly) for
the object file returned in the above find operation to remove the object file
first, for example, as:</p>
<pre class="literal-block">
$ rm ./CMakeFiles/&lt;source-dir-path&gt;.dir/SomeSourceFile.cpp.o
</pre>
<p>and then build it again, for example, with:</p>
<pre class="literal-block">
$ make SomeSourceFile.o
</pre>
<p>Again, the names of the target and the object file name an location depend on
the CMake version, the structure of your source directories and other factors
but the general process of using <tt class="docutils literal">make help | grep <span class="pre">&lt;some-file-base-name&gt;</span></tt> to
find the target name and then doing a find <tt class="docutils literal">find . <span class="pre">-name</span>
<span class="pre">&quot;*&lt;some-file-base-name&gt;*&quot;</span></tt> to find the actual object file path always works.</p>
<p>For this process to work correctly, you must be in the subdirectory where the
<tt class="docutils literal">TRIBITS_ADD_LIBRARY()</tt> or <tt class="docutils literal">TRIBITS_ADD_EXECUTABLE()</tt> command is called
from its <tt class="docutils literal">CMakeList.txt</tt> file, otherwise the object file targets will not be
listed by <tt class="docutils literal">make help</tt>.</p>
<p>NOTE: CMake does not seem to not check on dependencies when explicitly
building object files as shown above so you need to always delete the object
file first to make sure that it gets rebuilt correctly.</p>
</div>
<div class="section" id="building-with-verbose-output-without-reconfiguring">
<h2><a class="toc-backref" href="#id57">5.7&nbsp;&nbsp;&nbsp;Building with verbose output without reconfiguring</a></h2>
<p>One can get CMake to generate verbose make output at build type by just
setting the Makefile variable <tt class="docutils literal">VERBOSE=1</tt>, for example, as:</p>
<pre class="literal-block">
$ make  VERBOSE=1 [&lt;SOME_TARGET&gt;]
</pre>
<p>Any number of compile or linking problem can be quickly debugged by seeing the
raw compile and link lines.  See <a class="reference internal" href="#building-a-single-object-file">Building a single object file</a> for more
details.</p>
</div>
<div class="section" id="relink-a-target-without-considering-dependencies">
<h2><a class="toc-backref" href="#id58">5.8&nbsp;&nbsp;&nbsp;Relink a target without considering dependencies</a></h2>
<p>CMake provides a way to rebuild a target without considering its dependencies
using:</p>
<pre class="literal-block">
$ make &lt;SOME_TARGET&gt;/fast
</pre>
</div>
</div>
<div class="section" id="testing-with-ctest">
<h1><a class="toc-backref" href="#id59">6&nbsp;&nbsp;&nbsp;Testing with CTest</a></h1>
<p>This section assumes one is using the CMake Makefile generator described
above.  Also, the <tt class="docutils literal">ctest</tt> does not consider make dependencies when running
so the software must be completely built before running <tt class="docutils literal">ctest</tt> as described
here.</p>
<div class="section" id="running-all-tests">
<h2><a class="toc-backref" href="#id60">6.1&nbsp;&nbsp;&nbsp;Running all tests</a></h2>
<p>To run all of the defined tests (i.e. created using <tt class="docutils literal">TRIBITS_ADD_TEST()</tt> or
<tt class="docutils literal">TRIBITS_ADD_ADVANCED_TEST()</tt>) use:</p>
<pre class="literal-block">
$ ctest -j&lt;N&gt;
</pre>
<p>(where <tt class="docutils literal">&lt;N&gt;</tt> is an integer for the number of processes to try to run tests
in parallel).  A summary of what tests are run and their pass/fail status will
be printed to the screen.  Detailed output about each of the tests is archived
in the generate file:</p>
<pre class="literal-block">
Testing/Temporary/LastTest.log
</pre>
<p>where CTest creates the <tt class="docutils literal">Testing</tt> directory in the local directory where you
run it from.</p>
<p>NOTE: The <tt class="docutils literal"><span class="pre">-j&lt;N&gt;</span></tt> argument allows CTest to use more processes to run tests.
This will intelligently load ballance the defined tests with multiple
processes (i.e. MPI tests) and will try not exceed the number of processes
<tt class="docutils literal">&lt;N&gt;</tt>.  However, if tests are defined that use more that <tt class="docutils literal">&lt;N&gt;</tt> processes,
then CTest will still run the test but will not run any other tests while the
limit of <tt class="docutils literal">&lt;N&gt;</tt> processes is exceeded.  To exclude tests that require more
than <tt class="docutils literal">&lt;N&gt;</tt> processes, set the cache variable <tt class="docutils literal">MPI_EXEC_MAX_NUMPROCS</tt> (see
<a class="reference internal" href="#configuring-with-mpi-support">Configuring with MPI support</a>).</p>
</div>
<div class="section" id="only-running-tests-for-a-single-package">
<h2><a class="toc-backref" href="#id61">6.2&nbsp;&nbsp;&nbsp;Only running tests for a single package</a></h2>
<p>Tests for just a single TriBITS package can be run with:</p>
<pre class="literal-block">
$ ctest -j4 -L &lt;TRIBITS_PACKAGE&gt;
</pre>
<p>or:</p>
<pre class="literal-block">
$ cd packages/&lt;TRIBITS_PACKAGE&gt;
$ ctest -j4
</pre>
<p>This will run tests for packages and subpackages inside of the parent package
<tt class="docutils literal">&lt;TRIBITS_PACKAGE&gt;</tt>.</p>
<p>NOTE: CTest has a number of ways to filter what tests get run.  You can use
the test name using <tt class="docutils literal"><span class="pre">-E</span></tt>, you can exclude tests using <tt class="docutils literal"><span class="pre">-I</span></tt>, and there are
other approaches as well.  See <tt class="docutils literal">ctest <span class="pre">--help</span></tt> and online documentation, and
experiment for more details.</p>
</div>
<div class="section" id="running-a-single-test-with-full-output-to-the-console">
<h2><a class="toc-backref" href="#id62">6.3&nbsp;&nbsp;&nbsp;Running a single test with full output to the console</a></h2>
<p>To run just a single test and send detailed output directly to the console,
one can run:</p>
<pre class="literal-block">
$ ctest -R ^&lt;FULL_TEST_NAME&gt;$ -VV
</pre>
<p>However, when running just a single test, it is usally better to just run the
test command manually to allow passing in more options.  To see what the actual test command is, use:</p>
<pre class="literal-block">
$ ctest -R ^&lt;FULL_TEST_NAME&gt;$ -VV -N
</pre>
<p>This will only print out the test command that <tt class="docutils literal">ctest</tt> runs and show the
working directory.  To run the test exactly as <tt class="docutils literal">ctest</tt> would, cd into the
shown working directory and run the shown command.</p>
</div>
<div class="section" id="overridding-test-timeouts">
<h2><a class="toc-backref" href="#id63">6.4&nbsp;&nbsp;&nbsp;Overridding test timeouts</a></h2>
<p>The configured test timeout described in <tt class="docutils literal">Setting test timeouts at configure
time</tt> can be overridden on the CTest command-line as:</p>
<pre class="literal-block">
$ ctest --timeout &lt;maxSeconds&gt;
</pre>
<p>This will override the configured cache variable <tt class="docutils literal">DART_TESTING_TIMEOUT</tt>.</p>
<p><strong>WARNING:</strong> Do not try to use <tt class="docutils literal"><span class="pre">--timeout=&lt;maxSeconds&gt;</span></tt> or CTest will just
ignore the argument!</p>
</div>
<div class="section" id="running-memory-checking">
<h2><a class="toc-backref" href="#id64">6.5&nbsp;&nbsp;&nbsp;Running memory checking</a></h2>
<p>To configure for running memory testing with <tt class="docutils literal">valgrind</tt>, use:</p>
<pre class="literal-block">
-D MEMORYCHECK_COMMAND=&lt;abs-path-to-valgrind&gt;/valgrind \
-D MEMORYCHECK_SUPPRESSIONS_FILE=&lt;abs-path-to-supp-file0&gt; \
-D MEMORYCHECK_COMMAND_OPTIONS=&quot;-q --trace-children=yes --tool=memcheck \
  --leak-check=yes --workaround-gcc296-bugs=yes \
  --num-callers=50 --suppressions=&lt;abs-path-to-supp-file1&gt; \
  ... --suppressions=&lt;abs-path-to-supp-fileN&gt;&quot;
</pre>
<p>Above, you have to set the absolute path to the valgrind executable to run
using <tt class="docutils literal">MEMORYCHECK_COMMAND</tt> as CMake will not find this for you by default.
To use a single valgrind suppression file, just set
<tt class="docutils literal">MEMORYCHECK_SUPPRESSIONS_FILE</tt> to the path of that suppression file as
shown above.  To add other suppression files, they have to be added as other
general valgrind arguments in <tt class="docutils literal">MEMORYCHECK_COMMAND_OPTIONS</tt> as shown.</p>
<p>After configuring with the above options, to run the memory tests for all
enabled tests, from the <strong>base</strong> project build directory, do:</p>
<pre class="literal-block">
$ ctest -T memcheck
</pre>
<p>This will run valgrind on <strong>every</strong> test command that is run by ctest.</p>
<p>To run valgrind on the tests for a single package, from the <strong>base</strong> project
directory, do:</p>
<pre class="literal-block">
$ ctest -T memcheck -L &lt;TRIBITS_PACKAGE&gt;
</pre>
<p>To run valgrind on a specific test, from the <strong>base</strong> project directory, do:</p>
<pre class="literal-block">
$ ctest -T memcheck -R ^&lt;FULL_TEST_NAME&gt;$
</pre>
<p>Detailed output from valgrind is printed in the file:</p>
<pre class="literal-block">
Testing/Temporary/LastDynamicAnalysis_&lt;DATE_TIME&gt;.log
</pre>
<p>NOTE: If you try to run memory tests from any subdirectories, it will not
work.  You have to run them from the <strong>*base</strong> project build directory as
shown above.  A nice way to view valgrind results is to submit to CDash using
the <tt class="docutils literal">dashboard</tt> target (see <a class="reference internal" href="#dashboard-submissions">Dashboard submissions</a>).</p>
<p>NOTE: You have to use the valgrind option <tt class="docutils literal"><span class="pre">--trace-children=yes</span></tt> to trace
through child processes.  This is needed if you have tests that are given as
CMake -P scripts (such as advanced tests) or tests driven in bash, Perl,
Python, or other languages.</p>
</div>
</div>
<div class="section" id="installing">
<h1><a class="toc-backref" href="#id65">7&nbsp;&nbsp;&nbsp;Installing</a></h1>
<p>After a build and test of the software is complete, the software can be
installed.  Actually, to get ready for the install, the install directory must
be specified at configure time by setting the variable
<tt class="docutils literal">CMAKE_INSTALL_PREFIX</tt>.  The other commands described below can all be run
after the build and testing is complete.</p>
<div class="section" id="setting-the-install-prefix-at-configure-time">
<h2><a class="toc-backref" href="#id66">7.1&nbsp;&nbsp;&nbsp;Setting the install prefix at configure time</a></h2>
<p>In order to set up for the install, the install prefix should be set up at
configure time by setting, for example:</p>
<pre class="literal-block">
-D CMAKE_INSTALL_PREFIX=$HOME/install/&lt;Project&gt;/mpi/opt
</pre>
<p>The default location for the installation of libraries, headers, and
executables is given by the variables (with defaults):</p>
<pre class="literal-block">
-D &lt;Project&gt;_INSTALL_INCLUDE_DIR=&quot;include&quot; \
-D &lt;Project&gt;_INSTALL_LIB_DIR=&quot;lib&quot; \
-D &lt;Project&gt;_INSTALL_RUNTIME_DIR=&quot;bin&quot; \
-D &lt;Project&gt;_INSTALL_EXAMPLE_DIR=&quot;example&quot;
</pre>
<p>If these paths are relative (i.e. don't start with &quot;/&quot; and use type
<tt class="docutils literal">STRING</tt>) then they are relative to <tt class="docutils literal">${CMAKE_INSTALL_PREFIX}</tt>.  Otherwise
the paths can be absolute (use type <tt class="docutils literal">PATH</tt>) and don't have to be under
<tt class="docutils literal">${CMAKE_INSTALL_PREFIX}</tt>.  For example, to install each part in any
abritrary location use:</p>
<pre class="literal-block">
-D &lt;Project&gt;_INSTALL_INCLUDE_DIR=&quot;/usr/trilinos_include&quot; \
-D &lt;Project&gt;_INSTALL_LIB_DIR=&quot;/usr/trilinos_lib&quot; \
-D &lt;Project&gt;_INSTALL_RUNTIME_DIR=&quot;/usr/trilinos_bin&quot; \
-D &lt;Project&gt;_INSTALL_EXAMPLE_DIR=&quot;/usr/share/trilinos/examples&quot;
</pre>
<p>NOTE: The defaults for the above include paths will be set by the standard
CMake module <tt class="docutils literal">GNUInstallDirs</tt> if <tt class="docutils literal">&lt;Project&gt;_USE_GNUINSTALLDIRS=TRUE</tt> is
set.  Some projects have this set by default (see the <tt class="docutils literal">CMakeCache.txt</tt> after
configuring to see default being used by this project).</p>
<p>WARNING: To overwrite default relative paths, you must use the data type
<tt class="docutils literal">STRING</tt> for the cache variables.  If you don't, then CMake will use the
current binary directory for the base path.  Otherwise, if you want to specify
absolute paths, use the data type <tt class="docutils literal">PATH</tt> as shown above.</p>
</div>
<div class="section" id="avoiding-installing-libraries-and-headers">
<h2><a class="toc-backref" href="#id67">7.2&nbsp;&nbsp;&nbsp;Avoiding installing libraries and headers</a></h2>
<p>By default, any libraries and header files defined by in the TriBITS project
&lt;Project&gt; will get installed into the installation directories specified by
<tt class="docutils literal">CMAKE_INSTALL_PREFIX</tt>, <tt class="docutils literal">&lt;Project&gt;_INSTALL_INCLUDE_DIR</tt> and
<tt class="docutils literal">&lt;Project&gt;_INSTALL_LIB_DIR</tt>.  However, if the primary desire is to install
executables only, then the user can set:</p>
<pre class="literal-block">
-D &lt;Project&gt;_INSTALL_LIBRARIES_AND_HEADERS=ON
</pre>
<p>which, if in addition static libraries are being built
(i.e. <tt class="docutils literal">BUILD_SHARED_LIBS=OFF</tt>), this this option will result in no libraries
or headers being installed into the <tt class="docutils literal"><span class="pre">&lt;install&gt;/include/</span></tt> and
<tt class="docutils literal"><span class="pre">&lt;install&gt;/lib/</span></tt> directories, respectively.  However, if shared libraries
are being built (i.e. <tt class="docutils literal">BUILD_SHARED_LIBS=ON</tt>), they the libraries will be
installed in <tt class="docutils literal"><span class="pre">&lt;install&gt;/lib/</span></tt> along with the executables because the
executables can't run without the shared libraries being installed.</p>
</div>
<div class="section" id="installing-the-software">
<h2><a class="toc-backref" href="#id68">7.3&nbsp;&nbsp;&nbsp;Installing the software</a></h2>
<p>To install the software, type:</p>
<pre class="literal-block">
$ make install
</pre>
<p>Note that CMake actually puts in the build dependencies for installed targets
so in some cases you can just type <tt class="docutils literal">make <span class="pre">-j&lt;N&gt;</span> install</tt> and it will also
build the software.  However, it is advanced to always build and test the
software first before installing with:</p>
<pre class="literal-block">
$ make -j&lt;N&gt; &amp;&amp; ctest -j&lt;N&gt; &amp;&amp; make -j&lt;N&gt; install
</pre>
<p>This will ensure that everything is built correctly and all tests pass before
installing.</p>
</div>
</div>
<div class="section" id="packaging">
<h1><a class="toc-backref" href="#id69">8&nbsp;&nbsp;&nbsp;Packaging</a></h1>
<p>Packaged source and binary distributions can also be created using CMake and
CPack.</p>
<div class="section" id="creating-a-tarball-of-the-source-tree">
<h2><a class="toc-backref" href="#id70">8.1&nbsp;&nbsp;&nbsp;Creating a tarball of the source tree</a></h2>
<p>To create a source tarball of the project, first configure with the list of
desired packages (see <a class="reference internal" href="#selecting-the-list-of-packages-to-enable">Selecting the list of packages to enable</a>) and pass in</p>
<pre class="literal-block">
-D &lt;Project&gt;_ENABLE_CPACK_PACKAGING=ON
</pre>
<p>To actually generate the distribution files, use:</p>
<pre class="literal-block">
$ make package_source
</pre>
<p>The above command will tar up <em>everything</em> in the source tree except for files
explicitly excluded in the CMakeLists.txt files and packages that are not
enabled so make sure that you start with a totally clean source tree before
you do this.  You can clean the source tree first to remove all ignored files
using:</p>
<pre class="literal-block">
$ git clean -fd -x
</pre>
<p>You can include generated files in the tarball, such as Doxygen output files,
by creating them first, then running <tt class="docutils literal">make package_source</tt> and they will be
included in the distribution (unless there is an internal exclude set).</p>
<p>Disabled subpackages can be included or excluded from the tarball by setting
<tt class="docutils literal">&lt;Project&gt;_EXCLUDE_DISABLED_SUBPACKAGES_FROM_DISTRIBUTION</tt> (the TriBITS
project has its own default, check <tt class="docutils literal">CMakeCache.txt</tt> to see what the default
is).  If <tt class="docutils literal">&lt;Project&gt;_EXCLUDE_DISABLED_SUBPACKAGES_FROM_DISTRIBUTION=ON</tt> and
but one wants to include some subpackages that are otherwise excluded, just
enable them or their outer package so they will be included in the source
tarball.  To get a printout of set regular expresions that will be used to
match files to exclude, set:</p>
<pre class="literal-block">
-D &lt;Project&gt;_DUMP_CPACK_SOURCE_IGNORE_FILES=ON
</pre>
<p>While a set of default CPack source generator types is defined for this
project (see the <tt class="docutils literal">CMakeCache.txt</tt> file), it can be overridden using, for
example:</p>
<pre class="literal-block">
-D &lt;Project&gt;_CPACK_SOURCE_GENERATOR=&quot;TGZ;TBZ2&quot;
</pre>
<p>(see CMake documentation to find out the types of supported CPack source
generators on your system).</p>
<p>NOTE: When configuring from an untarred source tree that has missing packages,
one must configure with:</p>
<pre class="literal-block">
-D &lt;Project&gt;_ASSERT_MISSING_PACKAGES=OFF
</pre>
<p>Otherwise, TriBITS will error out complaining about missing packages.  (Note
that <tt class="docutils literal">&lt;Project&gt;_ASSERT_MISSING_PACKAGES</tt> will default to <tt class="docutils literal">`OFF`</tt> in
release mode, i.e. <tt class="docutils literal"><span class="pre">&lt;Project&gt;_ENABLE_DEVELOPMENT_MODE==OFF</span></tt>.)</p>
</div>
</div>
<div class="section" id="dashboard-submissions">
<h1><a class="toc-backref" href="#id71">9&nbsp;&nbsp;&nbsp;Dashboard submissions</a></h1>
<p>You can use the TriBITS scripting code to submit package-by-package build,
test, coverage, memcheck results to the project's CDash dashboard.</p>
<p>First, configure as normal but add the build and test parallel levels with:</p>
<pre class="literal-block">
-DCTEST_BUILD_FLAGS=-j4 -DCTEST_PARALLEL_LEVEL=4
</pre>
<p>(or with some other <tt class="docutils literal"><span class="pre">-j&lt;N&gt;</span></tt>).  Then, invoke the build, test and submit
with:</p>
<pre class="literal-block">
$ make dashboard
</pre>
<p>This invokes the advanced TriBITS CTest scripts to do an experimental build
for all of the packages that you have explicitly enabled.  The packages that
are implicitly enabled due to package dependencies are not directly processed
by the experimental_build_test.cmake script.</p>
<p>There are a number of options that you can set in the environment to control
what this script does.  This set of options can be found by doing:</p>
<pre class="literal-block">
$ grep 'SET_DEFAULT_AND_FROM_ENV(' \
    &lt;Project&gt;/cmake/tribits/ctest/TribitsCTestDriverCore.cmake
</pre>
<p>Currently, this options includes:</p>
<pre class="literal-block">
SET_DEFAULT_AND_FROM_ENV( CTEST_TEST_TYPE Nightly )
SET_DEFAULT_AND_FROM_ENV(&lt;Project&gt;_TRACK &quot;&quot;)
SET_DEFAULT_AND_FROM_ENV( CTEST_SITE ${CTEST_SITE_DEFAULT} )
SET_DEFAULT_AND_FROM_ENV( CTEST_DASHBOARD_ROOT &quot;&quot; )
SET_DEFAULT_AND_FROM_ENV( BUILD_TYPE NONE )
SET_DEFAULT_AND_FROM_ENV(COMPILER_VERSION UNKNOWN)
SET_DEFAULT_AND_FROM_ENV( CTEST_BUILD_NAME
SET_DEFAULT_AND_FROM_ENV( CTEST_START_WITH_EMPTY_BINARY_DIRECTORY TRUE )
SET_DEFAULT_AND_FROM_ENV( CTEST_WIPE_CACHE TRUE )
SET_DEFAULT_AND_FROM_ENV( CTEST_CMAKE_GENERATOR ${DEFAULT_GENERATOR})
SET_DEFAULT_AND_FROM_ENV( CTEST_DO_UPDATES TRUE )
SET_DEFAULT_AND_FROM_ENV( CTEST_GENERATE_DEPS_XML_OUTPUT_FILE FALSE )
SET_DEFAULT_AND_FROM_ENV( CTEST_UPDATE_ARGS &quot;&quot;)
SET_DEFAULT_AND_FROM_ENV( CTEST_UPDATE_OPTIONS &quot;&quot;)
SET_DEFAULT_AND_FROM_ENV( CTEST_BUILD_FLAGS &quot;-j2&quot;)
SET_DEFAULT_AND_FROM_ENV( CTEST_DO_BUILD TRUE )
SET_DEFAULT_AND_FROM_ENV( CTEST_DO_TEST TRUE )
SET_DEFAULT_AND_FROM_ENV( MPI_EXEC_MAX_NUMPROCS 4 )
SET_DEFAULT_AND_FROM_ENV( CTEST_PARALLEL_LEVEL 1 )
SET_DEFAULT_AND_FROM_ENV( &lt;Project&gt;_WARNINGS_AS_ERRORS_FLAGS &quot;&quot; )
SET_DEFAULT_AND_FROM_ENV( CTEST_DO_COVERAGE_TESTING FALSE )
SET_DEFAULT_AND_FROM_ENV( CTEST_COVERAGE_COMMAND gcov )
SET_DEFAULT_AND_FROM_ENV( CTEST_DO_MEMORY_TESTING FALSE )
SET_DEFAULT_AND_FROM_ENV( CTEST_MEMORYCHECK_COMMAND /usr/local/valgrind )
SET_DEFAULT_AND_FROM_ENV( CTEST_MEMORYCHECK_COMMAND_OPTIONS &quot;&quot; )
SET_DEFAULT_AND_FROM_ENV( CTEST_DO_SUBMIT TRUE )
SET_DEFAULT_AND_FROM_ENV( &lt;Project&gt;_ENABLE_SECONDARY_TESTED_CODE OFF )
SET_DEFAULT_AND_FROM_ENV( &lt;Project&gt;_ADDITIONAL_PACKAGES &quot;&quot; )
SET_DEFAULT_AND_FROM_ENV( &lt;Project&gt;_EXCLUDE_PACKAGES &quot;&quot; )
SET_DEFAULT_AND_FROM_ENV( &lt;Project&gt;_BRANCH &quot;&quot; )
SET_DEFAULT_AND_FROM_ENV( &lt;Project&gt;_REPOSITORY_LOCATION &quot;software.sandia.gov:/space/git/${CTEST_SOURCE_NAME}&quot; )
SET_DEFAULT_AND_FROM_ENV( &lt;Project&gt;_PACKAGES &quot;${&lt;Project&gt;_PACKAGES_DEFAULT}&quot; )
SET_DEFAULT_AND_FROM_ENV( CTEST_SELECT_MODIFIED_PACKAGES_ONLY OFF )
</pre>
<p>For example, to run an experimental build and in the process change the build
name and the options to pass to 'make', use:</p>
<pre class="literal-block">
$ env CTEST_BUILD_NAME=MyBuild make dashboard
</pre>
<p>After this finishes running, look for the build 'MyBuild' (or whatever build
name you used above) in the &lt;Project&gt; CDash dashboard.</p>
<p>It is useful to set CTEST_BUILD_NAME to some unique name to make it easier to
find your results in the CDash dashboard.</p>
<p>A number of the defaults set in TribitsCTestDriverCore.cmake are overridden
from experimental_build_test.cmake (such as CTEST_TEST_TYPE=Experimental) so
you will want to look at experimental_build_test.cmake to see how these are
changed.  The script experimental_build_test.cmake sets reasonable values for
these options in order to use the 'make dashboard' target in iterative
development for experimental builds.</p>
<p>The target 'dashboard' is not directly related to the built-in CMake targets
'Experimental*' that run standard dashboards with CTest without the custom
package-by-package driver in TribitsCTestDriverCore.cmake.  The
package-by-package extended CTest driver is more appropriate for &lt;Project&gt;.</p>
<p>Once you configure with -D&lt;Project&gt;_ENABLE_COVERAGE_TESTING=ON, the
environment variable CTEST_DO_COVERAGE_TESTING=TRUE is automatically set by
the target 'dashboard' so you don't have to set this yourself.</p>
<p>Doing a memory check with Valgrind requires that you set
CTEST_DO_MEMORY_TESTING=TRUE with the 'env' command as:</p>
<pre class="literal-block">
$ env CTEST_DO_MEMORY_TESTING=TRUE make dashboard
</pre>
<p>but also note that you may also need to set the valgrind command and options
with:</p>
<pre class="literal-block">
$ env CTEST_DO_MEMORY_TESTING=TRUE \
  CTEST_MEMORYCHECK_COMMAND=&lt;abs-path-to-valgrind&gt; \
  CTEST_MEMORYCHECK_COMMAND_OPTIONS=&quot;-q --trace-children=yes --tool=memcheck \
   --leak-check=yes --workaround-gcc296-bugs=yes \
   --num-callers=50 --suppressions=&lt;abs-path-to-supp-file1&gt; \
   ... --suppressions=&lt;abs-path-to-supp-fileN&gt;&quot; \
  make dashboard
</pre>
<p>The CMake cache variable &lt;Project&gt;_DASHBOARD_CTEST_ARGS can be set on the
cmake configure line in order to pass additional arguments to 'ctest -S' when
invoking the package-by-package CTest driver.  For example:</p>
<pre class="literal-block">
-D &lt;Project&gt;_DASHBOARD_CTEST_ARGS=&quot;-VV&quot;
</pre>
<p>will set verbose output with CTest.</p>
</div>
</div>
</body>
</html>
